From 4d27f56d050d8cd66a3c7474784ab559d3e6656d Mon Sep 17 00:00:00 2001 From: Hunter Johnston Date: Thu, 25 Jul 2024 18:13:14 -0400 Subject: [PATCH] more docs --- .../lib/content/api-reference/toggle-group.ts | 79 +++++++-------- .../src/lib/content/api-reference/toggle.ts | 32 +++--- .../src/lib/content/api-reference/toolbar.ts | 97 +++++++++---------- .../src/lib/content/api-reference/tooltip.ts | 73 +++++++------- 4 files changed, 136 insertions(+), 145 deletions(-) diff --git a/sites/docs/src/lib/content/api-reference/toggle-group.ts b/sites/docs/src/lib/content/api-reference/toggle-group.ts index d108671f3..103b3d726 100644 --- a/sites/docs/src/lib/content/api-reference/toggle-group.ts +++ b/sites/docs/src/lib/content/api-reference/toggle-group.ts @@ -1,51 +1,54 @@ import type { ToggleGroupItemPropsWithoutHTML, ToggleGroupRootPropsWithoutHTML } from "bits-ui"; -import { enums, union, withChildProps } from "$lib/content/api-reference/helpers.js"; +import { + createApiSchema, + createBooleanProp, + createEnumProp, + createFunctionProp, + createStringProp, + createUnionProp, + enums, + union, + withChildProps, +} from "$lib/content/api-reference/helpers.js"; import * as C from "$lib/content/constants.js"; -import type { APISchema } from "$lib/types/index.js"; -const root: APISchema = { +const root = createApiSchema({ title: "Root", description: "The root component which contains the toggle group items.", props: { - value: { - type: union(C.STRING, "string[]"), + type: createEnumProp({ + options: ["single", "multiple"], + description: "The type of toggle group.", + required: true, + }), + value: createUnionProp({ + options: ["string", "string[]"], description: - "The value of the toggle group. If the type is multiple, this will be an array of strings, otherwise it will be a string.", + "The value of the toggle group. If the `type` is `'multiple'`, this will be an array of strings, otherwise it will be a string.", bindable: true, - }, - onValueChange: { - type: { - type: C.FUNCTION, - definition: union("(value: string) => void", "(value: string[]) => void"), - }, + }), + onValueChange: createFunctionProp({ + definition: union("(value: string) => void", "(value: string[]) => void"), description: "A callback function called when the value of the toggle group changes. The type of the value is dependent on the type of the toggle group.", - }, - disabled: { + }), + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the switch is disabled.", - }, - loop: { + }), + loop: createBooleanProp({ default: C.TRUE, - type: C.BOOLEAN, description: "Whether or not the toggle group should loop when navigating.", - }, - orientation: { + }), + orientation: createEnumProp({ + options: [C.HORIZONTAL, C.VERTICAL], default: C.HORIZONTAL, - type: enums(C.HORIZONTAL, C.VERTICAL), description: "The orientation of the toggle group.", - }, - rovingFocus: { + }), + rovingFocus: createBooleanProp({ default: C.TRUE, - type: C.BOOLEAN, description: "Whether or not the toggle group should use roving focus when navigating.", - }, - type: { - default: "single", - description: "The type of toggle group.", - type: enums("single", "multiple"), - }, + }), ...withChildProps({ elType: "HTMLDivElement" }), }, dataAttributes: [ @@ -58,21 +61,19 @@ const root: APISchema = { description: "Present on the root element.", }, ], -}; +}); -const item: APISchema = { +const item = createApiSchema({ title: "Item", description: "An individual toggle item within the group.", props: { - value: { - type: C.STRING, + value: createStringProp({ description: "The value of the item.", - }, - disabled: { + }), + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the switch is disabled.", - }, + }), ...withChildProps({ elType: "HTMLButtonElement" }), }, dataAttributes: [ @@ -99,6 +100,6 @@ const item: APISchema = { description: "Present on the item elements.", }, ], -}; +}); export const toggleGroup = [root, item]; diff --git a/sites/docs/src/lib/content/api-reference/toggle.ts b/sites/docs/src/lib/content/api-reference/toggle.ts index 17439b53f..ec8ec4150 100644 --- a/sites/docs/src/lib/content/api-reference/toggle.ts +++ b/sites/docs/src/lib/content/api-reference/toggle.ts @@ -1,30 +1,30 @@ import type { ToggleRootPropsWithoutHTML } from "bits-ui"; -import { enums, withChildProps } from "$lib/content/api-reference/helpers.js"; +import { + createApiSchema, + createBooleanProp, + createFunctionProp, + enums, + withChildProps, +} from "$lib/content/api-reference/helpers.js"; import * as C from "$lib/content/constants.js"; -import type { APISchema } from "$lib/types/index.js"; -const root: APISchema = { +const root = createApiSchema({ title: "Root", description: "The toggle button.", props: { - pressed: { + pressed: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the toggle button is pressed.", bindable: true, - }, - onPressedChange: { - type: { - type: C.FUNCTION, - definition: "(checked: boolean) => void", - }, + }), + onPressedChange: createFunctionProp({ + definition: "(checked: boolean) => void", description: "A callback function called when the pressed state of the toggle changes.", - }, - disabled: { + }), + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the switch is disabled.", - }, + }), ...withChildProps({ elType: "HTMLButtonElement" }), }, dataAttributes: [ @@ -43,6 +43,6 @@ const root: APISchema = { description: "Present on the root element.", }, ], -}; +}); export const toggle = [root]; diff --git a/sites/docs/src/lib/content/api-reference/toolbar.ts b/sites/docs/src/lib/content/api-reference/toolbar.ts index a0877a2df..e5b29ca4a 100644 --- a/sites/docs/src/lib/content/api-reference/toolbar.ts +++ b/sites/docs/src/lib/content/api-reference/toolbar.ts @@ -5,27 +5,32 @@ import type { ToolbarLinkPropsWithoutHTML, ToolbarRootPropsWithoutHTML, } from "bits-ui"; -import { enums, union, withChildProps } from "$lib/content/api-reference/helpers.js"; +import { + createApiSchema, + createBooleanProp, + createEnumProp, + createFunctionProp, + createStringProp, + createUnionProp, + enums, + union, + withChildProps, +} from "$lib/content/api-reference/helpers.js"; import * as C from "$lib/content/constants.js"; -import type { APISchema } from "$lib/types/index.js"; -const root: APISchema = { +const root = createApiSchema({ title: "Root", description: "The root component which contains the toolbar.", props: { - loop: { + loop: createBooleanProp({ default: C.TRUE, - type: C.BOOLEAN, description: "Whether or not the toolbar should loop when navigating.", - }, - orientation: { + }), + orientation: createEnumProp({ + options: [C.HORIZONTAL, C.VERTICAL], default: C.HORIZONTAL, - type: { - type: C.ENUM, - definition: enums(C.HORIZONTAL, C.VERTICAL), - }, description: "The orientation of the toolbar.", - }, + }), ...withChildProps({ elType: "HTMLDivElement" }), }, dataAttributes: [ @@ -38,17 +43,16 @@ const root: APISchema = { description: "Present on the root element.", }, ], -}; +}); -const button: APISchema = { +const button = createApiSchema({ title: "Button", description: "A button in the toolbar.", props: { - disabled: { + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the button is disabled.", - }, + }), ...withChildProps({ elType: "HTMLButtonElement" }), }, dataAttributes: [ @@ -57,9 +61,9 @@ const button: APISchema = { description: "Present on the button element.", }, ], -}; +}); -const link: APISchema = { +const link = createApiSchema({ title: "Link", description: "A link in the toolbar.", props: withChildProps({ elType: "HTMLAnchorElement" }), @@ -69,38 +73,32 @@ const link: APISchema = { description: "Present on the link element.", }, ], -}; +}); -const group: APISchema = { +const group = createApiSchema({ title: "Group", description: "A group of toggle items in the toolbar.", props: { - value: { - type: { - type: C.UNION, - definition: union(C.STRING, "string[]"), - }, + type: createEnumProp({ + options: ["single", "multiple"], + default: "'single'", + description: "The type of toggle group.", + required: true, + }), + value: createUnionProp({ + options: ["string", "string[]"], description: "The value of the toggle group. If the type is multiple, this will be an array of strings, otherwise it will be a string.", bindable: true, - }, - onValueChange: { - type: C.FUNCTION, + }), + onValueChange: createFunctionProp({ + definition: union("(value: string) => void", "(value: string[]) => void"), description: "A callback function called when the value changes.", - }, - disabled: { + }), + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the switch is disabled.", - }, - type: { - default: "single", - description: "The type of toggle group.", - type: { - type: C.ENUM, - definition: enums("single", "multiple"), - }, - }, + }), ...withChildProps({ elType: "HTMLDivElement" }), }, dataAttributes: [ @@ -109,22 +107,21 @@ const group: APISchema = { description: "Present on the group element.", }, ], -}; +}); -const groupItem: APISchema = { +const groupItem = createApiSchema({ title: "GroupItem", description: "A toggle item in the toolbar toggle group.", props: { - value: { - type: C.STRING, + value: createStringProp({ description: "The value of the toolbar toggle group item. When the toolbar toggle group item is selected, toolbar the toggle group's value will be set to this value if in single mode, or this value will be pushed to the toggle group's array value if in multiple mode.", - }, - disabled: { + required: true, + }), + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the item is disabled.", - }, + }), ...withChildProps({ elType: "HTMLButtonElement" }), }, dataAttributes: [ @@ -147,6 +144,6 @@ const groupItem: APISchema = { description: "Present on the item element.", }, ], -}; +}); export const toolbar = [root, button, link, group, groupItem]; diff --git a/sites/docs/src/lib/content/api-reference/tooltip.ts b/sites/docs/src/lib/content/api-reference/tooltip.ts index 4911b43fe..e274d41fd 100644 --- a/sites/docs/src/lib/content/api-reference/tooltip.ts +++ b/sites/docs/src/lib/content/api-reference/tooltip.ts @@ -8,6 +8,10 @@ import type { import { arrowProps, childrenSnippet, + createApiSchema, + createBooleanProp, + createFunctionProp, + createNumberProp, dirProp, dismissableLayerProps, enums, @@ -17,48 +21,42 @@ import { withChildProps, } from "$lib/content/api-reference/helpers.js"; import * as C from "$lib/content/constants.js"; -import type { APISchema, PropSchema } from "$lib/types/index.js"; +import type { APISchema } from "$lib/types/index.js"; -const delayDuration: PropSchema = { - type: C.NUMBER, +const delayDuration = createNumberProp({ default: "700", description: "The amount of time in milliseconds to delay opening the tooltip when hovering over the trigger.", -}; +}); -const disableHoverableContent: PropSchema = { - type: C.BOOLEAN, +const disableHoverableContent = createBooleanProp({ default: C.FALSE, description: "Whether or not to disable the hoverable content. This is useful when the content contains interactive elements.", -}; +}); -const disabled: PropSchema = { - type: C.BOOLEAN, +const disabled = createBooleanProp({ default: C.FALSE, description: "Whether or not the tooltip is disabled.", -}; +}); -const disableCloseOnTriggerClick: PropSchema = { - type: C.BOOLEAN, +const disableCloseOnTriggerClick = createBooleanProp({ default: C.FALSE, description: "Whether or not to close the tooltip when pressing the escape key. This is useful when the content contains interactive elements.", -}; +}); -const skipDelayDuration: PropSchema = { - type: C.NUMBER, +const skipDelayDuration = createNumberProp({ default: "300", description: "The amount of time in milliseconds to delay opening the tooltip when the user has used their mouse to hover over the trigger.", -}; +}); -const ignoreNonKeyboardFocus: PropSchema = { - type: C.BOOLEAN, +const ignoreNonKeyboardFocus = createBooleanProp({ default: C.FALSE, description: "Whether or not to ignore the tooltip when the focus is not on the trigger. This is useful when the content contains interactive elements.", -}; +}); export const provider: APISchema = { title: "Provider", @@ -75,23 +73,19 @@ export const provider: APISchema = { }, }; -export const root: APISchema = { +export const root = createApiSchema({ title: "Root", description: "The root component containing the parts of the tooltip.", props: { - open: { - type: C.BOOLEAN, - default: "false", + open: createBooleanProp({ + default: C.FALSE, description: "The open state of the tooltip component.", bindable: true, - }, - onOpenChange: { - type: { - type: C.FUNCTION, - definition: "(open: boolean) => void", - }, + }), + onOpenChange: createFunctionProp({ + definition: "(open: boolean) => void", description: "A callback that fires when the open state changes.", - }, + }), disabled, delayDuration, disableHoverableContent, @@ -99,18 +93,17 @@ export const root: APISchema = { ignoreNonKeyboardFocus, children: childrenSnippet(), }, -}; +}); -export const trigger: APISchema = { +export const trigger = createApiSchema({ title: "Trigger", description: "A component which triggers the opening and closing of the tooltip on hover or focus.", props: { - disabled: { + disabled: createBooleanProp({ default: C.FALSE, - type: C.BOOLEAN, description: "Whether or not the tooltip trigger is disabled.", - }, + }), ...withChildProps({ elType: "HTMLButtonElement" }), }, dataAttributes: [ @@ -125,9 +118,9 @@ export const trigger: APISchema = { description: "Present on the trigger element.", }, ], -}; +}); -export const content: APISchema = { +export const content = createApiSchema({ title: "Content", description: "The contents of the tooltip which are displayed when the tooltip is open.", props: { @@ -144,9 +137,9 @@ export const content: APISchema = { description: "Present on the content element.", }, ], -}; +}); -export const arrow: APISchema = { +export const arrow = createApiSchema({ title: "Arrow", description: "An optional arrow element which points to the trigger when the tooltip is open.", props: arrowProps, @@ -160,6 +153,6 @@ export const arrow: APISchema = { description: "Present on the arrow element.", }, ], -}; +}); export const tooltip = [root, trigger, content, arrow];