@lostgradient/cinder 0.4.1 → 0.6.0

package/src/components/button/README.md

@@ -1,51 +0,0 @@
-# Button
-
-A clickable button or anchor with built-in loading state, icon slots, and a discriminated prop union that forces consumers to provide an accessible name at compile time.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Button from '@lostgradient/cinder/button';
-</script>
-
-<Button variant="primary" size="md" label="Save" />
-```
-
-When `href` is set, the component renders as `<a>`; otherwise it renders as `<button>`. Setting `loading` swaps in a spinner, blocks the consumer's `onclick`, forces `aria-disabled` / `aria-busy`, and strips `href` to prevent navigation.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop           | Type                                                                                                       | Required | Default       | Description                                                                                                                                                                                                                                         |
-| -------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                                                                                                   | no       | —             | Custom class merged with `.cinder-button`.                                                                                                                                                                                                          |
-| `fullWidth`    | `boolean`                                                                                                  | no       | `false`       | Expand to container width.                                                                                                                                                                                                                          |
-| `href`         | `string`                                                                                                   | no       | —             | Render as an anchor `<a>` element with this href.                                                                                                                                                                                                   |
-| `iconOnly`     | `boolean`                                                                                                  | no       | `false`       | Render the button with only an icon. Requires an accessible name source.                                                                                                                                                                            |
-| `label`        | `string`                                                                                                   | no       | —             | Visible text label. Must be non-empty if provided.                                                                                                                                                                                                  |
-| `loading`      | `boolean`                                                                                                  | no       | `false`       | Disable the button and show a spinner.                                                                                                                                                                                                              |
-| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                                             | no       | `"md"`        | Size of the button.                                                                                                                                                                                                                                 |
-| `variant`      | `"primary"` \| `"secondary"` \| `"soft"` \| `"danger"` \| `"soft-danger"` \| `"ghost"` \| `"ghost-danger"` | no       | `"secondary"` | Visual style.                                                                                                                                                                                                                                       |
-| `children`     | `(opaque)`                                                                                                 | no       | —             | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                          |
-| `leadingIcon`  | `(opaque)`                                                                                                 | no       | —             | DECORATIVE icon rendered before the label/children. Always wrapped in aria-hidden. If the icon conveys meaning, supply accessible text via `label`/`aria-label` instead. Not expressible in JSON Schema; see the component types for the signature. |
-| `trailingIcon` | `(opaque)`                                                                                                 | no       | —             | DECORATIVE icon rendered after the label/children. Always wrapped in aria-hidden. Same accessible-name guidance as `leadingIcon`. Not expressible in JSON Schema; see the component types for the signature.                                        |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/button/button.constraints.ts

@@ -1,102 +0,0 @@
-import { defineConstraints } from '../../_internal/constraints.ts';
-
-export default defineConstraints({
-  component: 'button',
-  summary:
-    'Button requires exactly one visual content source and, when rendered icon-only, an accessible name from aria-label, aria-labelledby, or a non-empty label prop.',
-  rules: [
-    {
-      id: 'visual-content-source',
-      severity: 'error',
-      description:
-        'Button must have exactly one visual content source: a visible label (label + iconOnly false), children content (children + iconOnly false), or icon-only mode (iconOnly true with at least one icon or children)',
-      kind: 'exactlyOne',
-      of: [
-        // Branch 1: visible label text; iconOnly is false (default). Callers normalize the
-        // default value to false before evaluation — absent iconOnly is treated as false.
-        {
-          allOf: [
-            { prop: 'label', nonEmpty: true },
-            { prop: 'iconOnly', equals: false },
-          ],
-        },
-        // Branch 2: children snippet; iconOnly is false (default).
-        {
-          allOf: [{ snippet: 'children' }, { prop: 'iconOnly', equals: false }],
-        },
-        // Branch 3: icon-only mode — iconOnly must be true and at least one visual source present.
-        {
-          allOf: [
-            { prop: 'iconOnly', equals: true },
-            {
-              anyOf: [
-                { prop: 'leadingIcon', exists: true },
-                { prop: 'trailingIcon', exists: true },
-                { snippet: 'children' },
-              ],
-            },
-          ],
-        },
-      ],
-    },
-    {
-      id: 'accessible-name',
-      severity: 'error',
-      description:
-        'Icon-only buttons must have an accessible name via aria-label, aria-labelledby, or a non-empty label prop',
-      kind: 'anyOf',
-      when: { prop: 'iconOnly', equals: true },
-      of: [
-        { prop: 'aria-label', nonEmpty: true },
-        { prop: 'aria-labelledby', nonEmpty: true },
-        { prop: 'label', nonEmpty: true },
-      ],
-    },
-  ],
-  examples: {
-    valid: [
-      {
-        title: 'Visible label',
-        code: '<Button label="Save" />',
-      },
-      {
-        title: 'Children as content',
-        code: '<Button><span>Save</span></Button>',
-      },
-      {
-        title: 'Icon-only with label as accessible name',
-        code: '<Button iconOnly={true} label="Close">{@render closeIcon()}</Button>',
-      },
-      {
-        title: 'Icon-only with aria-label',
-        code: '<Button iconOnly={true} aria-label="Close">{@render closeIcon()}</Button>',
-      },
-      {
-        title: 'Icon-only with leadingIcon and label',
-        code: '<Button iconOnly={true} label="Settings">{@render settingsIcon()}</Button>',
-      },
-    ],
-    invalid: [
-      {
-        title: 'Icon-only with no accessible name',
-        code: '<Button iconOnly={true}>{@render closeIcon()}</Button>',
-        violates: 'accessible-name',
-      },
-      {
-        title: 'Both label and children as visual content',
-        code: '<Button label="Save"><span>Also save</span></Button>',
-        violates: 'visual-content-source',
-      },
-      {
-        title: 'No visual content at all',
-        code: '<Button />',
-        violates: 'visual-content-source',
-      },
-      {
-        title: 'Icon-only with no icon source',
-        code: '<Button iconOnly={true} label="Close" />',
-        violates: 'visual-content-source',
-      },
-    ],
-  },
-});

package/src/components/button/button.svelte

@@ -1,249 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category action
-   * @status stable
-   * @purpose Primary interactive control for triggering actions or rendering an anchor styled as a button via href.
-   * @tag action
-   * @tag cta
-   * @useWhen Triggering a discrete action such as submit, save, or delete.
-   * @useWhen Rendering a link that should look and behave like a button by passing href.
-   * @avoidWhen Toggling a binary on or off state — use toggle instead.
-   * @avoidWhen Selecting one of a small fixed set of options — use segmented-control instead.
-   * @related button-group, copy-button
-   */
-  export type { ButtonProps, ButtonSize, ButtonVariant } from './button.types.ts';
-</script>
-
-<script lang="ts">
-  import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
-
-  import { classNames } from '../../utilities/class-names.ts';
-  import { devWarn } from '../../utilities/dev-warn.ts';
-  import type { ButtonProps } from './button.types.ts';
-
-  // Destructured props let the Phase 4 analyzer read names + defaults straight off the AST.
-  // `...rest` carries the remaining native HTML attributes through to the underlying element.
-  //
-  // ARIA + onclick are destructured explicitly because:
-  //  - Leaving them in `rest` would cause Svelte's spread to render our internally-computed
-  //    values LAST, clobbering any consumer-provided aria-disabled / aria-busy. Destructuring
-  //    gives us control of the resolved value per attribute.
-  //  - `onclick` must be wrapped during `loading` so the consumer handler doesn't fire — just
-  //    stripping `href` blocks navigation but the click event still bubbles.
-  const {
-    variant = 'secondary',
-    size = 'md',
-    fullWidth = false,
-    loading = false,
-    iconOnly = false,
-    leadingIcon,
-    trailingIcon,
-    children,
-    label,
-    class: customClassName,
-    href,
-    onclick: consumerOnClick,
-    'aria-disabled': consumerAriaDisabled,
-    'aria-busy': consumerAriaBusy,
-    'aria-label': ariaLabel,
-    'aria-labelledby': ariaLabelledBy,
-    'aria-expanded': ariaExpanded,
-    'aria-controls': ariaControls,
-    'aria-haspopup': ariaHaspopup,
-    ...rest
-  }: ButtonProps = $props();
-
-  // Prop-derived values must use `$derived` so they update when the consumer flips a prop
-  // (most importantly `loading`) after the initial render.
-  const mergedClassName = $derived(classNames('cinder-button', customClassName));
-  const dataAttributes = $derived({
-    'data-cinder-variant': variant,
-    'data-cinder-size': size,
-    'data-cinder-full-width': fullWidth ? '' : undefined,
-    'data-cinder-loading': loading ? '' : undefined,
-    'data-cinder-icon-only': iconOnly ? '' : undefined,
-  });
-
-  // When loading, force aria-disabled/aria-busy to 'true' so assistive tech always hears the
-  // loading state. When not loading, preserve whatever the consumer passed so the component
-  // doesn't silently erase their intent.
-  const resolvedAriaDisabled = $derived(loading ? 'true' : consumerAriaDisabled);
-  const resolvedAriaBusy = $derived(loading ? 'true' : consumerAriaBusy);
-
-  // Normalize ARIA label props: an empty string `aria-label=""` suppresses text-content fallback
-  // in the accessible-name computation (ARIA spec §4.3) without providing a name. Convert empty
-  // strings to `undefined` so the DOM attribute is omitted and the fallback (sr-only label text,
-  // or button text content) remains the accessible name. Guards and sr-only suppression use the
-  // normalized values for consistency.
-  const resolvedAriaLabel = $derived(
-    typeof ariaLabel === 'string' && ariaLabel.trim().length > 0 ? ariaLabel : undefined,
-  );
-  const resolvedAriaLabelledBy = $derived(
-    typeof ariaLabelledBy === 'string' && ariaLabelledBy.trim().length > 0
-      ? ariaLabelledBy
-      : undefined,
-  );
-
-  // `rest` is typed as the union of both branches' attribute sets minus the keys we
-  // destructured. TypeScript can't narrow a destructured remainder per branch, so each
-  // template arm casts `rest` to the attribute shape its element actually accepts. The cast
-  // is safe because the `#if href !== undefined` discriminant has already chosen the branch.
-  // These are plain `const` casts — `rest` from `$props()` is already reactive, so the
-  // template spread re-reads consumer prop changes without an intermediate `$derived` node.
-  const anchorAttributes = rest as Omit<
-    HTMLAnchorAttributes,
-    | 'class'
-    | 'href'
-    | 'tabindex'
-    | 'onclick'
-    | 'aria-disabled'
-    | 'aria-busy'
-    | 'aria-label'
-    | 'aria-labelledby'
-    | 'aria-expanded'
-    | 'aria-controls'
-    | 'aria-haspopup'
-  >;
-  const buttonAttributes = rest as Omit<
-    HTMLButtonAttributes,
-    | 'class'
-    | 'type'
-    | 'disabled'
-    | 'onclick'
-    | 'aria-disabled'
-    | 'aria-busy'
-    | 'aria-label'
-    | 'aria-labelledby'
-    | 'aria-expanded'
-    | 'aria-controls'
-    | 'aria-haspopup'
-  >;
-
-  // Branch-specific prop reads stay `$derived` because they extract a *value* off `rest`
-  // (a property access snapshots, unlike the spread of `rest` itself which re-reads the
-  // reactive proxy). Keeping these derived ensures consumer `tabindex` / `type` / `disabled`
-  // changes after mount still propagate to the rendered attributes.
-  const anchorTabIndex = $derived(
-    (rest as { tabindex?: HTMLAnchorAttributes['tabindex'] }).tabindex,
-  );
-  const buttonType = $derived((rest as { type?: HTMLButtonAttributes['type'] }).type);
-  const buttonDisabled = $derived((rest as { disabled?: boolean }).disabled ?? false);
-
-  type ButtonOrAnchorClickHandler = (
-    event: MouseEvent & {
-      currentTarget: EventTarget & (HTMLButtonElement | HTMLAnchorElement);
-    },
-  ) => void;
-
-  /**
-   * Wrap the consumer's onclick so it doesn't fire during loading. `preventDefault()` blocks
-   * the browser's default navigation on anchor left-clicks; stripping `href` in the template
-   * handles middle-click / Ctrl-click new-tab paths. Not calling `stopPropagation()` on
-   * purpose — unrelated ancestor handlers (analytics, form listeners) should still see the
-   * event; only the consumer's own button handler is skipped.
-   */
-  function handleClick(
-    event: MouseEvent & {
-      currentTarget: EventTarget & (HTMLButtonElement | HTMLAnchorElement);
-    },
-  ): void {
-    if (loading) {
-      event.preventDefault();
-      return;
-    }
-    if (typeof consumerOnClick === 'function') {
-      (consumerOnClick as ButtonOrAnchorClickHandler)(event);
-    }
-  }
-
-  // Dev-mode guards. devWarn no-ops in production (bundler DCE strips the call when DEV=false).
-  // Guards run reactively so prop changes after mount also surface issues.
-  $effect(() => {
-    // Guard 1 — Updated baseline: warn when the button has no accessible name at all.
-    // Use the normalized resolved values so an empty aria-label="" doesn't falsely satisfy the check.
-    const hasLabel = typeof label === 'string' && label.trim().length > 0;
-    const hasChildren = Boolean(children);
-    const hasAriaLabel = resolvedAriaLabel !== undefined;
-    const hasAriaLabelledBy = resolvedAriaLabelledBy !== undefined;
-    if (!hasLabel && !hasChildren && !hasAriaLabel && !hasAriaLabelledBy) {
-      devWarn(
-        '[cinder/Button] rendered without an accessible name — pass a non-empty `label`, `children`, `aria-label`, or `aria-labelledby`.',
-      );
-    }
-
-    // Guard 2 — icon-only accessible name: children alone does not count because it may be a
-    // non-text SVG. Requires aria-label, aria-labelledby, or a non-empty label string.
-    if (iconOnly && !hasAriaLabel && !hasAriaLabelledBy && !hasLabel) {
-      devWarn(
-        '[cinder/Button] iconOnly=true requires aria-label, aria-labelledby, or a non-empty label.',
-      );
-    }
-
-    // Guard 3 — icon-only visual: a blank square is a real UI failure, not just an a11y issue.
-    if (iconOnly && !leadingIcon && !trailingIcon && !children) {
-      devWarn(
-        '[cinder/Button] iconOnly=true requires a visible icon — pass leadingIcon, trailingIcon, or children.',
-      );
-    }
-  });
-</script>
-
-{#snippet buttonContent()}
-  {#if leadingIcon}
-    <span class="cinder-button__icon" aria-hidden="true">{@render leadingIcon()}</span>
-  {/if}
-  {#if iconOnly}
-    {#if !resolvedAriaLabel && !resolvedAriaLabelledBy && label}
-      <span class="cinder-sr-only">{label}</span>
-    {/if}
-    {#if children}
-      <span class="cinder-button__icon" aria-hidden="true">{@render children()}</span>
-    {/if}
-  {:else if children}
-    {@render children()}
-  {:else}
-    {label}
-  {/if}
-  {#if trailingIcon}
-    <span class="cinder-button__icon" aria-hidden="true">{@render trailingIcon()}</span>
-  {/if}
-{/snippet}
-
-{#if href !== undefined}
-  <a
-    {...anchorAttributes}
-    href={loading ? undefined : href}
-    tabindex={loading ? -1 : anchorTabIndex}
-    class={mergedClassName}
-    {...dataAttributes}
-    aria-disabled={resolvedAriaDisabled}
-    aria-busy={resolvedAriaBusy}
-    aria-label={resolvedAriaLabel}
-    aria-labelledby={resolvedAriaLabelledBy}
-    aria-expanded={ariaExpanded}
-    aria-controls={ariaControls}
-    aria-haspopup={ariaHaspopup}
-    onclick={handleClick}
-  >
-    {@render buttonContent()}
-  </a>
-{:else}
-  <button
-    {...buttonAttributes}
-    type={buttonType ?? 'button'}
-    class={mergedClassName}
-    {...dataAttributes}
-    disabled={buttonDisabled || loading}
-    aria-disabled={resolvedAriaDisabled}
-    aria-busy={resolvedAriaBusy}
-    aria-label={resolvedAriaLabel}
-    aria-labelledby={resolvedAriaLabelledBy}
-    aria-expanded={ariaExpanded}
-    aria-controls={ariaControls}
-    aria-haspopup={ariaHaspopup}
-    onclick={handleClick}
-  >
-    {@render buttonContent()}
-  </button>
-{/if}

package/src/components/button/button.types.ts

@@ -1,120 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
-
-/**
- * Visual style of the button.
- *
- * `secondary` is an outline-style button (filled surface + border). It is kept as `secondary`
- * rather than `outline` because: (a) today's `secondary` is already outline-flavored, (b) `ghost`
- * covers the transparent-background case, and (c) 27+ call sites depend on `secondary` today.
- *
- * `soft` / `soft-danger` use a tinted fill with no border — mid-emphasis between `ghost` and
- * `primary`/`danger`. Background is `color-mix(in oklch, accent, transparent 88%)` so it
- * resolves against the current theme's accent/danger color in both light and dark modes.
- *
- * @default `"secondary"`
- */
-export type ButtonVariant =
-  | 'primary'
-  | 'secondary'
-  | 'soft'
-  | 'danger'
-  | 'soft-danger'
-  | 'ghost'
-  | 'ghost-danger';
-
-/**
- * Size of the button. All sizes use compact visual heights; see button.a11y.md for touch-target guidance.
- *
- * @default `"md"`
- */
-export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-
-type SharedBase = {
-  /** Visual style. */
-  variant?: ButtonVariant;
-  /** Size of the button. */
-  size?: ButtonSize;
-  /** Expand to container width. */
-  fullWidth?: boolean;
-  /** Disable the button and show a spinner. */
-  loading?: boolean;
-  /** DECORATIVE icon rendered before the label/children. Always wrapped in aria-hidden.
-   *  If the icon conveys meaning, supply accessible text via `label`/`aria-label` instead. */
-  leadingIcon?: Snippet;
-  /** DECORATIVE icon rendered after the label/children. Always wrapped in aria-hidden.
-   *  Same accessible-name guidance as `leadingIcon`. */
-  trailingIcon?: Snippet;
-  /** Custom class merged with `.cinder-button`. */
-  class?: string;
-};
-
-// At least one of `label` or `children` must be provided so the button has an accessible name.
-//
-// The union shape (rather than `label?: string; children?: Snippet`) gives TypeScript a
-// compile-time guarantee that a consumer can't write `<Button />` with neither. The Phase 4
-// analyzer reads this two-variant shape to generate correct prop-control UI for each branch.
-// Runtime limitation: `string` includes `""`, so a literal empty label still satisfies
-// `WithLabel`. The dev-mode guard in the instance script catches that case.
-//
-// `iconOnly` lives only in the union branches (not SharedBase) so the discriminant is real:
-// `WithChildren` genuinely forbids `iconOnly={true}`, and `WithIconOnly` requires it.
-type WithLabel = { label: string; children?: Snippet; iconOnly?: false };
-type WithChildren = { label?: string; children: Snippet; iconOnly?: false };
-type IconOnlyAccessibleName =
-  | { label: string; 'aria-label'?: string; 'aria-labelledby'?: string }
-  | { label?: string; 'aria-label': string; 'aria-labelledby'?: string }
-  | { label?: string; 'aria-label'?: string; 'aria-labelledby': string };
-type IconOnlyVisual =
-  | { children: Snippet; leadingIcon?: Snippet; trailingIcon?: Snippet }
-  | { children?: Snippet; leadingIcon: Snippet; trailingIcon?: Snippet }
-  | { children?: Snippet; leadingIcon?: Snippet; trailingIcon: Snippet };
-// Icon-only buttons require a name source and a visual icon source at compile time.
-// `children` is accepted as the visual icon only; it is not a name source in this mode.
-type WithIconOnly = { iconOnly: true } & IconOnlyAccessibleName & IconOnlyVisual;
-type SharedProps = SharedBase & (WithLabel | WithChildren | WithIconOnly);
-
-type ButtonOnlyProps = SharedProps & Omit<HTMLButtonAttributes, 'class'> & { href?: undefined };
-type LinkButtonProps = SharedProps & Omit<HTMLAnchorAttributes, 'class'> & { href: string };
-
-/** Props for the Button component. */
-export type ButtonProps = ButtonOnlyProps | LinkButtonProps;
-
-/**
- * Cinder-specific props for the Button component, used by the schema generator.
- * Excludes the inherited HTML attribute surface that consumers can spread via
- * `...rest` — those are documented in the underlying element's MDN reference.
- */
-export interface ButtonSchemaProps {
-  /**
-   * Visual style.
-   * @default "secondary"
-   */
-  variant?: ButtonVariant;
-  /**
-   * Size of the button.
-   * @default "md"
-   */
-  size?: ButtonSize;
-  /**
-   * Expand to container width.
-   * @default false
-   */
-  fullWidth?: boolean;
-  /**
-   * Disable the button and show a spinner.
-   * @default false
-   */
-  loading?: boolean;
-  /**
-   * Render the button with only an icon. Requires an accessible name source.
-   * @default false
-   */
-  iconOnly?: boolean;
-  /** Render as an anchor `<a>` element with this href. */
-  href?: string;
-  /** Visible text label. Must be non-empty if provided. */
-  label?: string;
-  /** Custom class merged with `.cinder-button`. */
-  class?: string;
-}

package/src/components/button/index.ts

@@ -1,6 +0,0 @@
-import './button.css';
-import Button from './button.svelte';
-
-export default Button;
-export type { ButtonProps, ButtonSize, ButtonVariant } from './button.types.ts';
-export { Button };

package/src/components/button-group/README.md

@@ -1,43 +0,0 @@
-# ButtonGroup
-
-Clusters related action buttons into a unified visual group with shared borders.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ButtonGroup from '@lostgradient/cinder/button-group';
-</script>
-
-<ButtonGroup />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop          | Type                           | Required | Default | Description                                                                                                                                       |
-| ------------- | ------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`                       | no       | —       | Additional class merged with `.cinder-button-group`.                                                                                              |
-| `label`       | `string`                       | no       | —       | Inline accessible name for the group, applied as `aria-label`. Provide exactly one of `label` or `labelledBy`.                                    |
-| `labelledBy`  | `string`                       | no       | —       | The `id` of a visible heading element that already names the group, applied as `aria-labelledby`. Provide exactly one of `label` or `labelledBy`. |
-| `orientation` | `"horizontal"` \| `"vertical"` | no       | —       | Orientation of the visual collapse. Default: 'horizontal'.                                                                                        |
-| `children`    | `(opaque)`                     | yes      | —       | Buttons (or split-button compositions) to render inside the group. Not expressible in JSON Schema; see the component types for the signature.     |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->