@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/toggle/toggle.schema.ts

@@ -0,0 +1,64 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description:
+        'Native id placed on the `<button>`; the rendered label uses `aria-labelledby` to name it (label id is derived as `${id}-label`).',
+    },
+    checked: {
+      type: 'boolean',
+      description: 'Whether the toggle is currently checked. Bindable — defaults to false.',
+    },
+    label: {
+      type: 'string',
+      description:
+        'Visible label text. Always the accessible name, even when `hideLabel` is set. Required.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Prevents interaction when true. Sets `disabled` attribute.',
+    },
+    hideLabel: {
+      type: 'boolean',
+      description:
+        'Visually hide the rendered label while keeping it as the accessible name. Use for icon-only or inline contexts.',
+    },
+    name: {
+      type: 'string',
+      description:
+        'Form field name. When set, a hidden checkbox mirrors `checked` so the toggle\nparticipates in native form submission. Omit for purely client-side toggles\n(no hidden input is rendered, so there is zero overhead).',
+    },
+    value: {
+      type: 'string',
+      description:
+        "Value submitted for the hidden checkbox when `checked` and `name` is set.\nMirrors native checkbox semantics: the pair `name=value` is sent only while\nchecked. Defaults to `'on'`. Ignored when `name` is unset.",
+    },
+    form: {
+      type: 'string',
+      description:
+        'Associates the hidden checkbox with a form by id, matching the native\n`form` attribute. Lets the toggle submit with a form it is not nested in.\nIgnored when `name` is unset.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-toggle` on the switch button.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id', 'label'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'onValueChange',
+        reason: 'function-or-snippet',
+        description:
+          'Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/toggle/toggle.svelte

@@ -0,0 +1,73 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { commitValue } from '../../utilities/value-change.ts';
+let { id, checked = $bindable(false), onValueChange, label, disabled, hideLabel = false, name, value = 'on', form, class: customClassName, } = $props();
+// A switch implies an immediate-effect setting, so Toggle deliberately does
+// NOT take on `required`/`error` validation semantics — a deferred boolean in
+// a submit form should use Checkbox instead (see the module docstring). It
+// does, however, inherit `disabled` from a wrapping FormField so a disabled
+// field group greys out the switch alongside its peers.
+const context = getFormFieldContext();
+const resolvedDisabled = $derived(disabled ?? context?.disabled ?? false);
+const labelId = $derived(`${id}-label`);
+function toggle() {
+    if (!resolvedDisabled) {
+        commitValue(!checked, onValueChange, (next) => {
+            checked = next;
+        });
+    }
+}
+</script>
+
+<span class="cinder-toggle-field">
+  <button
+    {id}
+    type="button"
+    role="switch"
+    aria-checked={checked}
+    aria-labelledby={labelId}
+    disabled={resolvedDisabled}
+    onclick={toggle}
+    class={classNames('cinder-toggle', customClassName)}
+    data-cinder-checked={checked ? '' : undefined}
+  >
+    <span aria-hidden="true" class="cinder-toggle__thumb"></span>
+  </button>
+  {#if name}
+    <!--
+      Form participation: a `hidden` checkbox mirrors `checked` so the toggle
+      submits with a native form. The <button role="switch"> stays the only thing
+      users tab to or operate. We use the `hidden` attribute (display:none) rather
+      than a visually-hidden + aria-hidden + tabindex="-1" input: a display:none
+      control is genuinely non-focusable and out of the accessibility tree, so it
+      avoids the aria-hidden-focus WCAG violation (aria-hidden on a still-focusable
+      element). `hidden` form controls STILL submit when named, checked, and not
+      disabled — only `disabled` excludes a control from the form data set.
+      Rendered only when `name` is set, so a client-side-only toggle pays nothing.
+    -->
+    <input type="checkbox" hidden {name} {value} {form} disabled={resolvedDisabled} bind:checked />
+  {/if}
+  <!--
+    The label is a <span> (not a <label for>) named via aria-labelledby. A native
+    <label for> targeting the <button> would forward a synthetic click to it,
+    which — combined with the button's own onclick — double-toggles in some
+    engines. aria-labelledby supplies the accessible name, and the span's own
+    onclick gives click-to-toggle. toggle() is disabled-guarded, so clicking the
+    label of a disabled toggle is a no-op.
+  -->
+  <span
+    id={labelId}
+    class="cinder-toggle-field__label"
+    role="presentation"
+    data-hidden={hideLabel || undefined}
+    data-disabled={resolvedDisabled || undefined}
+    onclick={toggle}
+  >
+    {label}
+  </span>
+</span>

package/src/components/toggle/toggle.types.ts

@@ -0,0 +1,49 @@
+/**
+ * Props for the Toggle component.
+ *
+ * Uses the WAI-ARIA switch pattern (`role="switch"` + `aria-checked`) — the
+ * visible UI is a sliding-thumb pill, so the accessible role must match what
+ * sighted users see. Use Toggle for "this thing is on / off" affordances
+ * (notifications enabled, dark mode, etc.). For a toggle button that
+ * changes the state of something else without representing a binary
+ * on/off (e.g. bold formatting), use Button with `aria-pressed`.
+ *
+ * The component renders its own label next to the switch, so consumers do not
+ * hand-roll an external one. `label` is always the accessible name (wired via
+ * `aria-labelledby`); `hideLabel` changes only the visual presentation and
+ * never removes the accessible name.
+ */
+export type ToggleProps = {
+  /** Native id placed on the `<button>`; the rendered label uses `aria-labelledby` to name it (label id is derived as `${id}-label`). */
+  id: string;
+  /** Whether the toggle is currently checked. Bindable — defaults to false. */
+  checked?: boolean;
+  /** Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. */
+  onValueChange?: (next: boolean) => boolean | void;
+  /** Visible label text. Always the accessible name, even when `hideLabel` is set. Required. */
+  label: string;
+  /** Prevents interaction when true. Sets `disabled` attribute. */
+  disabled?: boolean;
+  /** Visually hide the rendered label while keeping it as the accessible name. Use for icon-only or inline contexts. */
+  hideLabel?: boolean;
+  /**
+   * Form field name. When set, a hidden checkbox mirrors `checked` so the toggle
+   * participates in native form submission. Omit for purely client-side toggles
+   * (no hidden input is rendered, so there is zero overhead).
+   */
+  name?: string;
+  /**
+   * Value submitted for the hidden checkbox when `checked` and `name` is set.
+   * Mirrors native checkbox semantics: the pair `name=value` is sent only while
+   * checked. Defaults to `'on'`. Ignored when `name` is unset.
+   */
+  value?: string;
+  /**
+   * Associates the hidden checkbox with a form by id, matching the native
+   * `form` attribute. Lets the toggle submit with a form it is not nested in.
+   * Ignored when `name` is unset.
+   */
+  form?: string;
+  /** Additional class names merged with `.cinder-toggle` on the switch button. */
+  class?: string;
+};

package/src/components/toggle/toggle.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/toolbar/index.ts

@@ -0,0 +1,18 @@
+import ToolbarGroup from './toolbar-group.svelte';
+import ToolbarSpacer from './toolbar-spacer.svelte';
+import './toolbar.css';
+import ToolbarRoot from './toolbar.svelte';
+
+const Toolbar = Object.assign(ToolbarRoot, {
+  Group: ToolbarGroup,
+  Spacer: ToolbarSpacer,
+});
+
+export default Toolbar;
+export type {
+  ToolbarGroupProps,
+  ToolbarOrientation,
+  ToolbarProps,
+  ToolbarSpacerProps,
+} from './toolbar.types.ts';
+export { Toolbar, ToolbarGroup, ToolbarSpacer };

package/src/components/toolbar/toolbar-group.svelte

@@ -0,0 +1,27 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { class: className, orientation, children, role, ...rest } = $props();
+const normalizedAriaLabel = $derived(typeof rest['aria-label'] === 'string' && rest['aria-label'].trim().length > 0
+    ? rest['aria-label'].trim()
+    : undefined);
+const normalizedAriaLabelledBy = $derived(typeof rest['aria-labelledby'] === 'string' && rest['aria-labelledby'].trim().length > 0
+    ? rest['aria-labelledby'].trim()
+    : undefined);
+const hasAccessibleName = $derived(Boolean(normalizedAriaLabel || normalizedAriaLabelledBy));
+</script>
+
+<div
+  {...rest}
+  aria-label={normalizedAriaLabel}
+  aria-labelledby={normalizedAriaLabelledBy}
+  role={role ?? (hasAccessibleName ? 'group' : undefined)}
+  class={classNames('cinder-toolbar__group', className)}
+  data-cinder-toolbar-group=""
+  data-cinder-orientation={orientation}
+>
+  {@render children()}
+</div>

package/src/components/toolbar/toolbar-spacer.svelte

@@ -0,0 +1,23 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+let { class: className, flex = 1, ...rest } = $props();
+const resolvedFlex = $derived(typeof flex === 'number' && Number.isFinite(flex) && flex > 0 ? flex : 1);
+$effect(() => {
+    if (typeof flex === 'number' && Number.isFinite(flex) && flex > 0)
+        return;
+    devWarn('[cinder/Toolbar.Spacer] `flex` must be a positive finite number. Falling back to 1.');
+});
+</script>
+
+<div
+  {...rest}
+  aria-hidden="true"
+  class={classNames('cinder-toolbar__spacer', className)}
+  data-cinder-toolbar-spacer=""
+  style={`flex-grow: ${resolvedFlex};`}
+></div>

package/src/components/toolbar/toolbar.schema.ts

@@ -0,0 +1,31 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    orientation: {
+      enum: ['horizontal', 'vertical'],
+      description:
+        'Layout direction for keyboard ownership and vertical group separator placement.',
+      default: 'horizontal',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class merged with `.cinder-toolbar`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Controls rendered inside the toolbar.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/toolbar/toolbar.svelte

@@ -0,0 +1,350 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { on } from 'svelte/events';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { getFocusableIndex, handleRovingKeydown } from '../../utilities/roving-tabindex.ts';
+import { useMutationObserver } from '../../utilities/use-mutation-observer.svelte.ts';
+const focusableSelector = [
+    'button',
+    'a[href]',
+    'input',
+    'select',
+    'textarea',
+    '[tabindex]',
+    '[data-cinder-toolbar-item]',
+].join(',');
+let { class: className, orientation = 'horizontal', children, onkeydown: consumerOnKeyDown, onfocusin: consumerOnFocusIn, role: _role, 'aria-orientation': _ariaOrientation, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rest } = $props();
+let rootElement = null;
+let toolbarItems = $state([]);
+let activeItem = $state(null);
+const originalTabIndexes = new WeakMap();
+let previousManagedItems = new Set();
+let lastWarnedNameSource = '';
+function isHTMLElement(value) {
+    return value instanceof HTMLElement;
+}
+function isHiddenInput(element) {
+    return element instanceof HTMLInputElement && element.type === 'hidden';
+}
+function isEditableTarget(element) {
+    if (element instanceof HTMLTextAreaElement)
+        return true;
+    if (element instanceof HTMLInputElement) {
+        return ![
+            'button',
+            'checkbox',
+            'file',
+            'hidden',
+            'image',
+            'radio',
+            'range',
+            'reset',
+            'submit',
+        ].includes(element.type);
+    }
+    return element.isContentEditable;
+}
+function isSpinButtonLike(element) {
+    if (element.getAttribute('role') === 'spinbutton')
+        return true;
+    if (!(element instanceof HTMLInputElement))
+        return false;
+    return element.closest('.cinder-number-input') !== null;
+}
+function hasCollapsedSelectionAtBoundary(element, direction) {
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement))
+        return false;
+    if (typeof element.selectionStart !== 'number' || typeof element.selectionEnd !== 'number')
+        return false;
+    if (element.selectionStart !== element.selectionEnd)
+        return false;
+    const valueLength = element.value.length;
+    return direction === -1 ? element.selectionStart === 0 : element.selectionEnd === valueLength;
+}
+function placeCaret(element, placement) {
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement))
+        return;
+    if (typeof element.setSelectionRange !== 'function')
+        return;
+    const position = placement === 'end' ? element.value.length : 0;
+    element.setSelectionRange(position, position);
+}
+function isCssHidden(element) {
+    const elementStyle = getComputedStyle(element);
+    if (elementStyle.display === 'none' || elementStyle.visibility === 'hidden')
+        return true;
+    let current = element.parentElement;
+    while (current) {
+        if (getComputedStyle(current).display === 'none')
+            return true;
+        current = current.parentElement;
+    }
+    return false;
+}
+function isDisabledByFieldset(element) {
+    const disabledFieldset = element.closest('fieldset[disabled]');
+    if (!disabledFieldset)
+        return false;
+    const firstLegend = disabledFieldset.querySelector('legend');
+    return firstLegend ? !firstLegend.contains(element) : true;
+}
+function isEligibleToolbarItem(element) {
+    if (!rootElement || element === rootElement)
+        return false;
+    if (!rootElement.contains(element))
+        return false;
+    if (isHiddenInput(element))
+        return false;
+    if (element.hasAttribute('hidden'))
+        return false;
+    if (element.getAttribute('aria-hidden') === 'true')
+        return false;
+    if (element.getAttribute('aria-disabled') === 'true')
+        return false;
+    if ('disabled' in element && typeof element.disabled === 'boolean') {
+        if (element.disabled)
+            return false;
+    }
+    if (element.closest('[hidden],[aria-hidden=\"true\"],[data-cinder-toolbar-exclude]'))
+        return false;
+    if (element.closest('[inert]'))
+        return false;
+    if (isDisabledByFieldset(element))
+        return false;
+    if (isCssHidden(element))
+        return false;
+    const authoredTabIndex = element.getAttribute('tabindex');
+    if (authoredTabIndex === '-1' &&
+        !previousManagedItems.has(element) &&
+        !element.hasAttribute('data-cinder-toolbar-item')) {
+        return false;
+    }
+    return true;
+}
+function getToolbarItems() {
+    if (!rootElement)
+        return [];
+    return Array.from(rootElement.querySelectorAll(focusableSelector)).filter((element) => isEligibleToolbarItem(element));
+}
+function getActiveIndex(items, preferredItem) {
+    if (preferredItem) {
+        const preferredIndex = items.indexOf(preferredItem);
+        if (preferredIndex >= 0)
+            return preferredIndex;
+    }
+    return getFocusableIndex(-1, items.length);
+}
+function restoreDepartedItems(nextItems) {
+    const nextItemSet = new Set(nextItems);
+    for (const item of previousManagedItems) {
+        if (nextItemSet.has(item))
+            continue;
+        const original = originalTabIndexes.get(item);
+        if (original === null)
+            item.removeAttribute('tabindex');
+        else if (original !== undefined)
+            item.setAttribute('tabindex', original);
+        originalTabIndexes.delete(item);
+    }
+    previousManagedItems = nextItemSet;
+}
+function syncToolbarItems(preferredItem = activeItem) {
+    const items = getToolbarItems();
+    restoreDepartedItems(items);
+    if (items.length === 0) {
+        toolbarItems = [];
+        activeItem = null;
+        return;
+    }
+    for (const item of items) {
+        if (!originalTabIndexes.has(item)) {
+            originalTabIndexes.set(item, item.getAttribute('tabindex'));
+        }
+    }
+    const activeIndex = getActiveIndex(items, preferredItem);
+    const resolvedActiveItem = activeIndex >= 0 ? (items[activeIndex] ?? null) : null;
+    for (const [index, item] of items.entries()) {
+        const nextTabIndex = index === activeIndex ? 0 : -1;
+        if (item.tabIndex !== nextTabIndex) {
+            item.tabIndex = nextTabIndex;
+        }
+    }
+    toolbarItems = items;
+    activeItem = resolvedActiveItem;
+}
+function moveFocus(nextIndex, caretPlacement) {
+    const nextItem = toolbarItems[nextIndex];
+    if (!nextItem)
+        return;
+    activeItem = nextItem;
+    syncToolbarItems(nextItem);
+    nextItem.focus();
+    placeCaret(nextItem, caretPlacement);
+}
+function getCurrentToolbarIndex(target) {
+    return toolbarItems.indexOf(target);
+}
+function handleEditableEscape(target) {
+    if (!isEditableTarget(target))
+        return false;
+    const currentIndex = getCurrentToolbarIndex(target);
+    if (currentIndex < 0)
+        return false;
+    const nextIndex = currentIndex < toolbarItems.length - 1
+        ? currentIndex + 1
+        : currentIndex > 0
+            ? currentIndex - 1
+            : -1;
+    if (nextIndex < 0)
+        return false;
+    moveFocus(nextIndex, nextIndex > currentIndex ? 'start' : 'end');
+    return true;
+}
+function handleToolbarKeyDown(event) {
+    consumerOnKeyDown?.(event);
+    if (event.defaultPrevented)
+        return;
+    if (!isHTMLElement(event.target))
+        return;
+    const target = event.target.closest(focusableSelector);
+    if (!target || !toolbarItems.includes(target))
+        return;
+    const currentIndex = getCurrentToolbarIndex(target);
+    if (currentIndex < 0)
+        return;
+    const horizontal = orientation !== 'vertical';
+    const targetIsEditable = isEditableTarget(target);
+    if (event.key === 'Escape' && targetIsEditable) {
+        if (!handleEditableEscape(target))
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+    }
+    if ((event.key === 'Home' || event.key === 'End') && targetIsEditable) {
+        return;
+    }
+    if (horizontal && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {
+        if (targetIsEditable &&
+            !hasCollapsedSelectionAtBoundary(target, event.key === 'ArrowLeft' ? -1 : 1)) {
+            return;
+        }
+    }
+    if (!horizontal && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+        if (targetIsEditable || isSpinButtonLike(target))
+            return;
+    }
+    if (horizontal && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+        return;
+    }
+    if (!horizontal && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {
+        return;
+    }
+    const nextIndex = handleRovingKeydown(event, currentIndex, toolbarItems.length, {
+        horizontal,
+        vertical: !horizontal,
+    });
+    if (nextIndex === null || nextIndex === currentIndex)
+        return;
+    event.preventDefault();
+    event.stopPropagation();
+    moveFocus(nextIndex, event.key === 'ArrowLeft' || event.key === 'ArrowUp' || event.key === 'End' ? 'end' : 'start');
+}
+function handleToolbarFocusIn(event) {
+    consumerOnFocusIn?.(event);
+    if (!isHTMLElement(event.target))
+        return;
+    const target = event.target.closest(focusableSelector);
+    if (!target || !isEligibleToolbarItem(target))
+        return;
+    syncToolbarItems(target);
+}
+function resolveAccessibleNameSource() {
+    const inlineLabel = ariaLabel?.trim() ?? '';
+    const labelledBy = ariaLabelledBy?.trim() ?? '';
+    return inlineLabel || labelledBy;
+}
+function hasResolvedLabelledByText() {
+    if (!rootElement || !ariaLabelledBy)
+        return false;
+    const identifiers = ariaLabelledBy
+        .split(/\s+/)
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (identifiers.length === 0)
+        return false;
+    return identifiers.every((identifier) => {
+        const element = document.getElementById(identifier);
+        return element !== null && (element.textContent?.trim().length ?? 0) > 0;
+    });
+}
+function warnAboutAccessibleName() {
+    if (!rootElement)
+        return;
+    const warningKey = `${ariaLabel ?? ''}|${ariaLabelledBy ?? ''}`;
+    if (warningKey === lastWarnedNameSource)
+        return;
+    const inlineLabel = ariaLabel?.trim() ?? '';
+    if (inlineLabel.length > 0)
+        return;
+    if (ariaLabelledBy?.trim() && hasResolvedLabelledByText())
+        return;
+    lastWarnedNameSource = warningKey;
+    devWarn('[cinder/Toolbar] rendered without a resolvable accessible name. Pass a non-empty `aria-label` or `aria-labelledby` that points to non-empty text.');
+}
+function toolbarSetup(node) {
+    rootElement = node;
+    syncToolbarItems(untrack(() => activeItem));
+    const cleanupKeyboardListener = on(node, 'keydown', handleToolbarKeyDown, { capture: true });
+    const cleanupFocusInListener = on(node, 'focusin', handleToolbarFocusIn);
+    const detachMutationObserver = useMutationObserver(() => {
+        syncToolbarItems(activeItem);
+        warnAboutAccessibleName();
+    }, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: [
+            'aria-disabled',
+            'aria-hidden',
+            'aria-label',
+            'aria-labelledby',
+            'class',
+            'data-cinder-toolbar-exclude',
+            'data-cinder-toolbar-item',
+            'disabled',
+            'hidden',
+            'inert',
+            'style',
+            'type',
+        ],
+    })(node);
+    warnAboutAccessibleName();
+    return () => {
+        cleanupKeyboardListener();
+        cleanupFocusInListener();
+        detachMutationObserver?.();
+        rootElement = null;
+        restoreDepartedItems([]);
+    };
+}
+</script>
+
+<div
+  {...rest}
+  {@attach toolbarSetup}
+  role="toolbar"
+  aria-label={ariaLabel}
+  aria-labelledby={ariaLabelledBy}
+  aria-orientation={orientation === 'vertical' ? 'vertical' : undefined}
+  class={classNames('cinder-toolbar', className)}
+  data-cinder-orientation={orientation}
+  data-cinder-name-source={resolveAccessibleNameSource()}
+>
+  {@render children()}
+</div>