From cc27615e96b8bfea6821fe2b916e9d27b990b301 Mon Sep 17 00:00:00 2001 From: Ryan Gossiaux Date: Mon, 7 Mar 2022 16:34:56 -0800 Subject: [PATCH] Add JSDoc comments Yay --- src/lib/components/dialog/Dialog.svelte | 4 +++ .../components/disclosure/Disclosure.svelte | 1 + .../disclosure/DisclosurePanel.svelte | 4 ++- src/lib/components/listbox/Listbox.svelte | 4 +++ .../components/listbox/ListboxOption.svelte | 2 ++ .../components/listbox/ListboxOptions.svelte | 4 ++- src/lib/components/menu/MenuItem.svelte | 5 +++- src/lib/components/menu/MenuItems.svelte | 2 ++ .../components/popover/PopoverPanel.svelte | 7 +++++ .../components/radio-group/RadioGroup.svelte | 2 ++ .../radio-group/RadioGroupOption.svelte | 5 ++++ src/lib/components/switch/Switch.svelte | 1 + src/lib/components/tabs/Tab.svelte | 1 + src/lib/components/tabs/TabGroup.svelte | 7 +++++ .../transitions/TransitionChild.svelte | 14 +++++++++- .../transitions/TransitionRoot.svelte | 2 ++ src/lib/utils/Render.svelte | 26 +++++++++++++++++-- 17 files changed, 85 insertions(+), 6 deletions(-) diff --git a/src/lib/components/dialog/Dialog.svelte b/src/lib/components/dialog/Dialog.svelte index b740a8e..7e6e3d8 100644 --- a/src/lib/components/dialog/Dialog.svelte +++ b/src/lib/components/dialog/Dialog.svelte @@ -42,9 +42,13 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** Whether the `Dialog` is open */ open?: boolean; + /** The element that should receive focus when the Dialog is first opened */ initialFocus?: HTMLElement | null; + /** Whether the element should ignore the internally managed open/closed state */ static?: boolean; + /** Whether the element should be unmounted, instead of just hidden, based on the open/closed state */ unmount?: boolean; }; diff --git a/src/lib/components/disclosure/Disclosure.svelte b/src/lib/components/disclosure/Disclosure.svelte index 5f10e5b..99f4f00 100644 --- a/src/lib/components/disclosure/Disclosure.svelte +++ b/src/lib/components/disclosure/Disclosure.svelte @@ -45,6 +45,7 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** Whether the `Disclosure` should be open by default */ defaultOpen?: boolean; }; diff --git a/src/lib/components/disclosure/DisclosurePanel.svelte b/src/lib/components/disclosure/DisclosurePanel.svelte index fec4e42..ab9b370 100644 --- a/src/lib/components/disclosure/DisclosurePanel.svelte +++ b/src/lib/components/disclosure/DisclosurePanel.svelte @@ -9,8 +9,10 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { - unmount?: boolean; + /** Whether the element should ignore the internally managed open/closed state */ static?: boolean; + /** Whether the element should be unmounted, instead of just hidden, based on the open/closed state */ + unmount?: boolean; }; diff --git a/src/lib/components/listbox/Listbox.svelte b/src/lib/components/listbox/Listbox.svelte index f1770cf..519a6fd 100644 --- a/src/lib/components/listbox/Listbox.svelte +++ b/src/lib/components/listbox/Listbox.svelte @@ -50,12 +50,16 @@ return context; } + type TListboxProps< TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** Whether the entire `Listbox` and its children should be disabled */ disabled?: boolean; + /** Whether the entire `Listbox` should be oriented horizontally instead of vertically */ horizontal?: boolean; + /** The selected value */ value?: StateDefinition["value"]; }; diff --git a/src/lib/components/listbox/ListboxOption.svelte b/src/lib/components/listbox/ListboxOption.svelte index c371ced..ddc32ff 100644 --- a/src/lib/components/listbox/ListboxOption.svelte +++ b/src/lib/components/listbox/ListboxOption.svelte @@ -3,7 +3,9 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** The option value */ value: unknown; + /** Whether the option should be disabled for keyboard navigation and ARIA purposes */ disabled?: boolean; }; diff --git a/src/lib/components/listbox/ListboxOptions.svelte b/src/lib/components/listbox/ListboxOptions.svelte index 6bc1345..abdbcf3 100644 --- a/src/lib/components/listbox/ListboxOptions.svelte +++ b/src/lib/components/listbox/ListboxOptions.svelte @@ -3,8 +3,10 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { - unmount?: boolean; + /** Whether the element should ignore the internally managed open/closed state */ static?: boolean; + /** Whether the element should be unmounted, instead of just hidden, based on the open/closed state */ + unmount?: boolean; }; diff --git a/src/lib/components/menu/MenuItem.svelte b/src/lib/components/menu/MenuItem.svelte index 4067a49..23981ae 100644 --- a/src/lib/components/menu/MenuItem.svelte +++ b/src/lib/components/menu/MenuItem.svelte @@ -2,7 +2,10 @@ type TMenuItemProps< TSlotProps extends {}, TAsProp extends SupportedAs - > = TPassThroughProps & {}; + > = TPassThroughProps & { + /** Whether the item should be disabled for keyboard navigation and ARIA purposes */ + disabled?: boolean; + }; diff --git a/src/lib/components/popover/PopoverPanel.svelte b/src/lib/components/popover/PopoverPanel.svelte index 72741f6..1d54c23 100644 --- a/src/lib/components/popover/PopoverPanel.svelte +++ b/src/lib/components/popover/PopoverPanel.svelte @@ -12,8 +12,15 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** + * Whether the `PopoverPanel` should trap focus. + * If true, focus will move inside the `PopoverPanel` when it is opened, + * and if focus leaves the `PopoverPanel` it will close. + */ focus?: boolean; + /** Whether the element should ignore the internally managed open/closed state */ static?: boolean; + /** Whether the element should be unmounted, instead of just hidden, based on the open/closed state */ unmount?: boolean; }; diff --git a/src/lib/components/radio-group/RadioGroup.svelte b/src/lib/components/radio-group/RadioGroup.svelte index 43f6493..d7ceead 100644 --- a/src/lib/components/radio-group/RadioGroup.svelte +++ b/src/lib/components/radio-group/RadioGroup.svelte @@ -48,7 +48,9 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** The currently selected value in the `RadioGroup` */ value: StateDefinition["value"]; + /** Whether the `RadioGroup` and all of its `RadioGroupOption`s are disabled */ disabled?: boolean; }; diff --git a/src/lib/components/radio-group/RadioGroupOption.svelte b/src/lib/components/radio-group/RadioGroupOption.svelte index 147cf52..65289f7 100644 --- a/src/lib/components/radio-group/RadioGroupOption.svelte +++ b/src/lib/components/radio-group/RadioGroupOption.svelte @@ -3,7 +3,12 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** + * The value of the `RadioGroupOption`. + * The type should match the type of the value prop in the `RadioGroup` + */ value: unknown; + /** Whether the `RadioGroupOption` is disabled */ disabled?: boolean; }; diff --git a/src/lib/components/switch/Switch.svelte b/src/lib/components/switch/Switch.svelte index 9200f13..65eafb8 100644 --- a/src/lib/components/switch/Switch.svelte +++ b/src/lib/components/switch/Switch.svelte @@ -3,6 +3,7 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** Whether the switch is checked */ checked: boolean; }; diff --git a/src/lib/components/tabs/Tab.svelte b/src/lib/components/tabs/Tab.svelte index e00399c..0e4133b 100644 --- a/src/lib/components/tabs/Tab.svelte +++ b/src/lib/components/tabs/Tab.svelte @@ -3,6 +3,7 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** Whether the `Tab` is currently disabled */ disabled?: boolean; }; diff --git a/src/lib/components/tabs/TabGroup.svelte b/src/lib/components/tabs/TabGroup.svelte index 7d142a9..a04719e 100644 --- a/src/lib/components/tabs/TabGroup.svelte +++ b/src/lib/components/tabs/TabGroup.svelte @@ -41,8 +41,15 @@ TSlotProps extends {}, TAsProp extends SupportedAs > = TPassThroughProps & { + /** The index of the default selected tab */ defaultIndex?: number; + /** Whether the orientation of the `TabList` is vertical instead of horizontal */ vertical?: boolean; + /** + * Whether, in keyboard navigation, the Enter or Space key is necessary to change tabs. + * By default, the arrow keys will change tabs automatically without hitting Enter/Space. + * This has no impact on mouse behavior + */ manual?: boolean; }; diff --git a/src/lib/components/transitions/TransitionChild.svelte b/src/lib/components/transitions/TransitionChild.svelte index 5e6e4b7..0dd2ff1 100644 --- a/src/lib/components/transitions/TransitionChild.svelte +++ b/src/lib/components/transitions/TransitionChild.svelte @@ -2,15 +2,27 @@ export type TTransitionChildProps< TAsProp extends SupportedAs, TDefaultAs - > = TPassThroughProps<{}, TAsProp, TDefaultAs> & { + > = Omit, "class"> & { + /** Classes to add to the transitioning element during the entire enter phase */ enter?: string; + /** Classes to add to the transitioning element before the enter phase starts */ enterFrom?: string; + /** Classes to add to the transitioning element immediately after the enter phase starts */ enterTo?: string; + /** + * Classes to add to the transitioning element once the transition is done. + * These classes will persist after that until the leave phase + */ entered?: string; + /** Classes to add to the transitioning element during the entire leave phase */ leave?: string; + /** Classes to add to the transitioning element before the leave phase starts */ leaveFrom?: string; + /** Classes to add to the transitioning element immediately after the leave phase starts */ leaveTo?: string; + /** Whether the element should be unmounted, instead of just hidden, based on the open/closed state */ unmount?: boolean; + /** The class attribute for the transition element. These classes will always be present. */ class?: string; }; diff --git a/src/lib/components/transitions/TransitionRoot.svelte b/src/lib/components/transitions/TransitionRoot.svelte index c753534..5bafb5e 100644 --- a/src/lib/components/transitions/TransitionRoot.svelte +++ b/src/lib/components/transitions/TransitionRoot.svelte @@ -3,7 +3,9 @@ TAsProp extends SupportedAs, TDefaultAs > = TTransitionChildProps & { + /** Whether the children should be shown */ show?: boolean; + /** Whether the transition should run on initial mount */ appear?: boolean; }; diff --git a/src/lib/utils/Render.svelte b/src/lib/utils/Render.svelte index 780b5ef..aaceef7 100644 --- a/src/lib/utils/Render.svelte +++ b/src/lib/utils/Render.svelte @@ -44,15 +44,36 @@ TDefaultAs > = TRestProps> & { name: string; - as: TAsProp; slotProps: TSlotProps; el?: HTMLElement | null; - use?: HTMLActionArray; visible?: boolean; features?: Features; + as: TAsProp; static?: boolean; unmount?: boolean; + /** + * A list of actions to apply to the component's HTML element. + * + * Each action must take the form `[action]` or `[action, options]`: + * + * use={[[action1], [action2, action2Options], [action3]]} + */ + use?: HTMLActionArray; + /** + * The class attribute for this component. + * + * In addition to a regular string, this may be a function that returns a string. + * In that case, the function will be passed this component's slot props as an argument, + * allowing you to conditionally apply classes. See the component's documentation for more. + */ class?: ((props: TSlotProps) => string) | string; + /** + * The style attribute for this component. + * + * In addition to a regular string, this may be a function that returns a string. + * In that case, the function will be passed this component's slot props as an argument, + * allowing you to conditionally apply styles. See the component's documentation for more. + */ style?: ((props: TSlotProps) => string) | string; }; @@ -66,6 +87,7 @@ TRenderProps, TInternalProps | "as" | "static" | "unmount" > & { + /** The HTML element the component should render as */ as?: TAsProp; };