@lostgradient/cinder 0.5.0 → 0.6.0

package/src/components/autocomplete/autocomplete.types.ts

@@ -1,74 +0,0 @@
-import type { HTMLInputAttributes } from 'svelte/elements';
-
-export type AutocompleteSuggestion = {
-  /** Text committed into the input when this suggestion is completed. */
-  value: string;
-  /** Visible primary label. Defaults to `value` when omitted. */
-  label?: string;
-  /** Optional secondary text rendered under the label. */
-  description?: string;
-  /** When true, the suggestion is rendered but cannot be completed. */
-  disabled?: boolean;
-};
-
-export type AutocompleteSuggestionSourceContext = {
-  /** Aborted when a newer query supersedes this request or the component is destroyed. */
-  signal: AbortSignal;
-};
-
-export type AutocompleteSuggestionSource = (
-  query: string,
-  context: AutocompleteSuggestionSourceContext,
-) => AutocompleteSuggestion[] | Promise<AutocompleteSuggestion[]>;
-
-export type AutocompleteSchemaProps = {
-  /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. */
-  id?: string;
-  /** Bindable current text value of the input. */
-  value?: string;
-  suggestionSource?: AutocompleteSuggestionSource;
-  /** Visible label text rendered above the input and linked via `for`/`id`. */
-  label?: string;
-  /** Helper text rendered below the input and associated via `aria-describedby`. */
-  description?: string;
-  /** Error message rendered below the input; also sets `aria-invalid` on the input. */
-  error?: string;
-  /** Minimum number of characters the user must type before suggestions are requested. Default `1`. */
-  minQueryLength?: number;
-  /** Maximum number of suggestions rendered in the listbox at once. Default `50`. */
-  maxVisibleSuggestions?: number;
-  /** Placeholder text shown inside the input when it is empty. */
-  placeholder?: string;
-  /** When true, disables the input and prevents interaction, matching the native `disabled` attribute. */
-  disabled?: boolean;
-  /** Marks the input as required for form validation, matching the native `required` attribute. */
-  required?: boolean;
-  /** When true, the input value cannot be changed by the user, matching the native `readonly` attribute. */
-  readonly?: boolean;
-  /** Message shown in the listbox when the suggestion source returns no results. Default `"No suggestions"`. */
-  emptyMessage?: string;
-  /** Message shown in the listbox while the suggestion source is fetching results. Default `"Loading suggestions"`. */
-  loadingMessage?: string;
-  /** Additional class names merged onto the root wrapper element. */
-  class?: string;
-  oninput?: (value: string) => void;
-  oncomplete?: (suggestion: AutocompleteSuggestion) => void;
-};
-
-export type AutocompleteProps = Omit<
-  HTMLInputAttributes,
-  | 'type'
-  | 'value'
-  | 'oninput'
-  | 'onchange'
-  | 'onkeydown'
-  | 'onfocus'
-  | 'onblur'
-  | 'oncompositionstart'
-  | 'oncompositionend'
-  | 'disabled'
-  | 'required'
-  | 'readonly'
-  | 'role'
-> &
-  AutocompleteSchemaProps;

package/src/components/autocomplete/index.ts

@@ -1,11 +0,0 @@
-import './autocomplete.css';
-import Autocomplete from './autocomplete.svelte';
-
-export default Autocomplete;
-export type {
-  AutocompleteProps,
-  AutocompleteSchemaProps,
-  AutocompleteSuggestion,
-  AutocompleteSuggestionSource,
-  AutocompleteSuggestionSourceContext,
-} from './autocomplete.types.ts';

package/src/components/avatar/avatar.svelte

@@ -1,73 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status stable
-   * @purpose Profile graphic that renders a user image with automatic initials fallback when the source is missing or fails to load.
-   * @tag identity
-   * @tag image
-   * @useWhen Representing a person or account next to their name or activity.
-   * @useWhen Displaying initials when no avatar image is available.
-   * @avoidWhen Showing a small status or count indicator — use badge or status-dot instead.
-   * @related badge, status-dot, image
-   */
-  export type { AvatarProps, AvatarShape, AvatarSize } from './avatar.types.ts';
-</script>
-
-<script lang="ts">
-  import type { AvatarProps } from './avatar.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import VisuallyHidden from '../visually-hidden/visually-hidden.svelte';
-
-  let {
-    src,
-    alt,
-    name,
-    size = 'md',
-    shape = 'circle',
-    class: className,
-    ...rest
-  }: AvatarProps = $props();
-
-  // Track the specific URL that failed to load so a new src automatically
-  // gets a fresh chance, while a repeated failed src stays hidden.
-  let failedSource = $state<string | null>(null);
-
-  const showImage = $derived(!!src && failedSource !== src);
-  const accessibleAlt = $derived(alt ?? name ?? '');
-
-  const initials = $derived(computeInitials(name));
-
-  function computeInitials(value: string | undefined): string {
-    if (!value) return '';
-    const parts = value.trim().split(/\s+/).slice(0, 2);
-    return parts.map((part) => part.charAt(0).toUpperCase()).join('');
-  }
-</script>
-
-<span
-  class={classNames('cinder-avatar', className)}
-  data-cinder-size={size}
-  data-cinder-shape={shape}
-  {...rest}
->
-  {#if showImage}
-    <img
-      class="cinder-avatar__image"
-      {src}
-      alt={accessibleAlt}
-      onerror={() => {
-        failedSource = src ?? null;
-      }}
-    />
-  {:else if initials}
-    <span class="cinder-avatar__initials" aria-hidden="true">{initials}</span>
-    {#if accessibleAlt}
-      <VisuallyHidden>{accessibleAlt}</VisuallyHidden>
-    {/if}
-  {:else}
-    <!-- Fallback when neither image nor name is available. Render an empty
-         neutral surface; consumers should always supply at least one. -->
-    <span aria-hidden="true" class="cinder-avatar__placeholder"></span>
-  {/if}
-</span>

package/src/components/avatar/avatar.types.ts

@@ -1,33 +0,0 @@
-import type { HTMLAttributes } from 'svelte/elements';
-export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-export type AvatarShape = 'circle' | 'square';
-/**
- * Props for the Avatar component.
- *
- * Renders an image when `src` is supplied; falls back to initials computed
- * from `name` when the image is missing or fails to load. The `name` prop
- * is also used for the accessible name when no `alt` is supplied.
- *
- * When neither `src` nor `name` is provided, a decorative placeholder
- * (`aria-hidden`) renders and the avatar has no accessible name. If such a
- * placeholder-only avatar still needs to be announced (e.g. an "unassigned"
- * slot), supply an `aria-label` via the forwarded rest props — it lands on
- * the root element and names the avatar.
- */
-export type AvatarProps = HTMLAttributes<HTMLSpanElement> & {
-  /** Image source. When omitted, the initials fallback renders. */
-  src?: string;
-  /** Alternative text for the image. Defaults to `name` when present. */
-  alt?: string;
-  /**
-   * Display name used to compute initials when no image is available.
-   * Also used as the default `alt` for the image.
-   */
-  name?: string;
-  /** Size token. Default `md`. */
-  size?: AvatarSize;
-  /** Shape. Default `circle`. */
-  shape?: AvatarShape;
-  /** Additional class names merged with `.cinder-avatar`. */
-  class?: string;
-};

package/src/components/avatar/index.ts

@@ -1,6 +0,0 @@
-import './avatar.css';
-import Avatar from './avatar.svelte';
-
-export default Avatar;
-export type { AvatarProps, AvatarShape, AvatarSize } from './avatar.types.ts';
-export { Avatar };

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

@@ -1,195 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status stable
-   * @purpose Overlapping collaborator avatar stack built on the Avatar primitive with focusable names and overflow count.
-   * @tag identity
-   * @tag collaboration
-   * @useWhen Showing who is present, assigned, or collaborating in a compact surface.
-   * @useWhen Summarizing a bounded set of people with a visible overflow count.
-   * @avoidWhen Rendering a single person — use avatar instead.
-   * @avoidWhen Showing status, counts, or metadata labels unrelated to people — use badge, chip, or status-dot instead.
-   * @related avatar, badge, tooltip, status-dot
-   */
-  export type {
-    AvatarGroupItem,
-    AvatarGroupProps,
-    AvatarGroupZOrder,
-  } from './avatar-group.types.ts';
-</script>
-
-<script lang="ts">
-  import type { AvatarGroupProps } from './avatar-group.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import Avatar from '../avatar/avatar.svelte';
-  import Tooltip from '../tooltip/tooltip.svelte';
-
-  const defaultMaxVisible = 5;
-
-  let {
-    avatars = [],
-    maxVisible = defaultMaxVisible,
-    overlap = '0.75rem',
-    zOrder = 'last-on-top',
-    size = 'md',
-    shape = 'circle',
-    overflowLabel,
-    label = 'Collaborators',
-    'aria-label': consumerAriaLabel,
-    class: className,
-    style,
-    ...rest
-  }: AvatarGroupProps = $props();
-
-  // A consumer-provided `aria-label` wins over the `label` default; destructuring
-  // it out of `rest` (rather than letting `{...rest}` spread it) lets us resolve
-  // the accessible name explicitly instead of having the hard-coded default
-  // silently clobber it after the spread. An empty or whitespace-only
-  // `aria-label` is treated as absent (rendering `aria-label=""` would suppress
-  // the accessible-name computation per ARIA §4.3.2 without naming the region),
-  // so it falls back to `label` rather than producing a nameless `role="list"`.
-  const accessibleName = $derived(
-    typeof consumerAriaLabel === 'string' && consumerAriaLabel.trim().length > 0
-      ? consumerAriaLabel
-      : label,
-  );
-
-  const normalizedMaxVisible = $derived(normalizeMaxVisible(maxVisible));
-  const visibleCount = $derived(Math.min(normalizedMaxVisible, avatars.length));
-  const hiddenCount = $derived(Math.max(0, avatars.length - visibleCount));
-  const hasOverflow = $derived(hiddenCount > 0);
-  const computedOverflowLabel = $derived(overflowLabel ?? `${hiddenCount} more collaborators`);
-  const normalizedOverlap = $derived(normalizeOverlap(overlap));
-  const identityCounts = $derived(countAvatarIdentities(avatars));
-  const rootStyle = $derived(
-    [style, `--cinder-avatar-group-overlap: ${normalizedOverlap}`].filter(Boolean).join('; '),
-  );
-
-  const visibleAvatars = $derived(
-    avatars.slice(0, visibleCount).map((avatar, index) => ({
-      avatar,
-      key: getAvatarKey(avatar, index, identityCounts),
-      trimmedName: (avatar.name ?? '').trim(),
-      stackIndex: getVisibleStackIndex(index, visibleCount, zOrder),
-    })),
-  );
-
-  const overflowStackIndex = $derived(getOverflowStackIndex(visibleCount, zOrder));
-
-  function normalizeMaxVisible(value: number): number {
-    if (!Number.isFinite(value)) return defaultMaxVisible;
-    return Math.max(0, Math.floor(value));
-  }
-
-  function normalizeOverlap(value: string): string {
-    const trimmed = value.trim();
-    if (/^(?:0|(?:\d*\.)?\d+(?:px|rem|em|ch|ex|vw|vh|vmin|vmax|%))$/.test(trimmed)) {
-      return trimmed;
-    }
-    return '0.75rem';
-  }
-
-  function countAvatarIdentities(items: AvatarGroupProps['avatars']): Map<string, number> {
-    const counts = new Map<string, number>();
-    for (const avatar of items) {
-      const identity = avatar.id ?? avatar.name ?? '';
-      counts.set(identity, (counts.get(identity) ?? 0) + 1);
-    }
-    return counts;
-  }
-
-  function getAvatarKey(
-    avatar: AvatarGroupProps['avatars'][number],
-    index: number,
-    counts: Map<string, number>,
-  ): string {
-    const identity = avatar.id ?? avatar.name ?? '';
-    return counts.get(identity) === 1 ? identity : `${identity}:${index}`;
-  }
-
-  function getVisibleStackIndex(
-    index: number,
-    count: number,
-    order: NonNullable<AvatarGroupProps['zOrder']>,
-  ): number {
-    if (order === 'first-on-top') return count - index;
-    return index + 1;
-  }
-
-  function getOverflowStackIndex(
-    count: number,
-    order: NonNullable<AvatarGroupProps['zOrder']>,
-  ): number {
-    if (count === 0) return 0;
-    if (order === 'first-on-top') return 0;
-    return count + 1;
-  }
-
-  function avatarSourceProps(src: string | undefined): { src?: string } {
-    return src === undefined ? {} : { src };
-  }
-</script>
-
-<div
-  {...rest}
-  class={classNames('cinder-avatar-group', className)}
-  style={rootStyle}
-  role="list"
-  aria-label={accessibleName}
-  data-cinder-size={size}
-  data-cinder-shape={shape}
-  data-cinder-z-order={zOrder}
->
-  {#each visibleAvatars as item (item.key)}
-    <span
-      class="cinder-avatar-group__item"
-      role="listitem"
-      style={`--cinder-avatar-group-index: ${item.stackIndex}`}
-    >
-      {#if item.trimmedName}
-        <Tooltip text={item.trimmedName} describe={false}>
-          <!-- role="img" is the honest semantic: a NAMED composite image, not an
-               action control. The trigger only reveals a name tooltip on focus/
-               hover — it has no onclick/Enter/Space activation, so role="button"
-               would be a false affordance (announces "button" but does nothing →
-               WCAG 4.1.2). img takes its name from the author, so aria-label is
-               valid here (no aria-prohibited-attr). tabindex="0" on a non-
-               interactive role is permitted by ARIA and is purposeful: it gives
-               keyboard users the same name-disclosure pointer users get on hover.
-               The inner <Avatar> uses alt="" so its image doesn't double-name the
-               composite. -->
-          <span
-            class="cinder-avatar-group__trigger"
-            role="img"
-            tabindex="0"
-            aria-label={item.trimmedName}
-          >
-            <Avatar
-              {...avatarSourceProps(item.avatar.src)}
-              name={item.trimmedName}
-              alt=""
-              {size}
-              {shape}
-            />
-          </span>
-        </Tooltip>
-      {:else}
-        <span class="cinder-avatar-group__trigger">
-          <Avatar {...avatarSourceProps(item.avatar.src)} name="" alt="" {size} {shape} />
-        </span>
-      {/if}
-    </span>
-  {/each}
-
-  {#if hasOverflow}
-    <span
-      class="cinder-avatar-group__item cinder-avatar-group__overflow"
-      role="listitem"
-      aria-label={computedOverflowLabel}
-      style={`--cinder-avatar-group-index: ${overflowStackIndex}`}
-    >
-      +{hiddenCount}
-    </span>
-  {/if}
-</div>

package/src/components/avatar-group/avatar-group.types.ts

@@ -1,97 +0,0 @@
-import type { HTMLAttributes } from 'svelte/elements';
-import type { AvatarShape, AvatarSize } from '../avatar/avatar.types.ts';
-
-type AvatarGroupRootAttributes = Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
-
-export type AvatarGroupZOrder = 'first-on-top' | 'last-on-top';
-
-/**
- * @schemaObject
- */
-export type AvatarGroupItem = {
-  /** Stable identifier recommended for dynamic collaborator lists. */
-  id?: string;
-  /** Display name used for initials, tooltip text, and accessible naming. */
-  name: string;
-  /** Optional avatar image source. */
-  src?: string;
-};
-
-export type AvatarGroupProps = AvatarGroupRootAttributes & {
-  /** Collaborators to render in the stack. */
-  avatars: AvatarGroupItem[];
-  /**
-   * Accessible name for the avatar stack list.
-   * @default "Collaborators"
-   */
-  label?: string;
-  /**
-   * Maximum visible avatars before overflow.
-   * @default 5
-   */
-  maxVisible?: number;
-  /**
-   * Non-negative CSS length token for the amount each item overlaps its predecessor.
-   * @default "0.75rem"
-   */
-  overlap?: string;
-  /**
-   * Stacking order for visible avatars.
-   * @default "last-on-top"
-   */
-  zOrder?: AvatarGroupZOrder;
-  /**
-   * Size token forwarded to each visible Avatar.
-   * @default "md"
-   */
-  size?: AvatarSize;
-  /**
-   * Shape forwarded to each visible Avatar.
-   * @default "circle"
-   */
-  shape?: AvatarShape;
-  /** Accessible label for the overflow indicator. */
-  overflowLabel?: string;
-  /** Additional class names merged with `.cinder-avatar-group`. */
-  class?: string;
-};
-
-/** Cinder-specific props for the AvatarGroup component, used by the schema generator. */
-export interface AvatarGroupSchemaProps {
-  /** Collaborators to render in the stack. */
-  avatars: AvatarGroupItem[];
-  /**
-   * Accessible name for the avatar stack list.
-   * @default "Collaborators"
-   */
-  label?: string;
-  /**
-   * Maximum visible avatars before overflow.
-   * @default 5
-   */
-  maxVisible?: number;
-  /**
-   * Non-negative CSS length token for the amount each item overlaps its predecessor.
-   * @default "0.75rem"
-   */
-  overlap?: string;
-  /**
-   * Stacking order for visible avatars.
-   * @default "last-on-top"
-   */
-  zOrder?: AvatarGroupZOrder;
-  /**
-   * Size token forwarded to each visible Avatar.
-   * @default "md"
-   */
-  size?: AvatarSize;
-  /**
-   * Shape forwarded to each visible Avatar.
-   * @default "circle"
-   */
-  shape?: AvatarShape;
-  /** Accessible label for the overflow indicator. */
-  overflowLabel?: string;
-  /** Additional class names merged with `.cinder-avatar-group`. */
-  class?: string;
-}

package/src/components/avatar-group/index.ts

@@ -1,6 +0,0 @@
-import './avatar-group.css';
-import AvatarGroup from './avatar-group.svelte';
-
-export default AvatarGroup;
-export type { AvatarGroupItem, AvatarGroupProps, AvatarGroupZOrder } from './avatar-group.types.ts';
-export { AvatarGroup };

package/src/components/backdrop/backdrop.svelte

@@ -1,105 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category overlay
-   * @status beta
-   * @purpose Full-viewport fixed scrim primitive for custom overlay patterns such as loading dimmers and image lightboxes.
-   * @tag overlay
-   * @tag scrim
-   * @useWhen Providing a full-screen dimming layer behind a custom overlay that is not modal, drawer, or sheet.
-   * @useWhen Building a loading state that dims the full viewport while an async operation runs.
-   * @avoidWhen Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically.
-   * @avoidWhen Showing a side panel — use drawer instead.
-   * @avoidWhen Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native `<dialog>::backdrop` scrim.
-   * @related modal, drawer, sheet
-   */
-
-  /*
-   * Backdrop is a low-level primitive: it dims/captures pointer events and locks
-   * body scroll (`lockScroll`, default true), but it does NOT trap focus or
-   * isolate the content behind it from the keyboard. A keyboard user can still
-   * Tab to page content under an open backdrop. When you need that isolation
-   * (a full-page loading dimmer, a lightbox), apply `inert` to your page-content
-   * container while the backdrop is open and pair it with `@lostgradient/cinder/focus-trap`.
-   * Click-to-close via `onclick` is a pointer convenience — wire an Escape
-   * handler yourself for a keyboard dismiss path (e.g. on a lightbox).
-   */
-  export type { BackdropProps } from './backdrop.types.ts';
-</script>
-
-<script lang="ts">
-  import { fade } from 'svelte/transition';
-  import type { BackdropProps } from './backdrop.types.ts';
-  import { lockBodyScroll } from '../../_internal/overlay.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
-
-  const DEFAULT_TRANSITION_DURATION = 200;
-
-  let {
-    open,
-    invisible = false,
-    lockScroll = true,
-    transitionDuration = DEFAULT_TRANSITION_DURATION,
-    onclick,
-    class: className,
-    children,
-    ...rest
-  }: BackdropProps = $props();
-
-  // Respect prefers-reduced-motion: collapse the fade to an instant show/hide so
-  // the scrim does not animate for users who have opted out of motion.
-  const reducedMotion = useReducedMotion();
-  const effectiveDuration = $derived(reducedMotion.current ? 0 : transitionDuration);
-
-  // SSR/hydration gate (overlay contract — see _internal/overlay.ts / OVERLAY-POLICY.md).
-  // `$effect` runs only on the client, so `hydrated` stays false through SSR and the
-  // server emits no scrim. Wrapping the element in `{#if hydrated}` keeps SSR HTML free
-  // of a dimmer whose scroll lock (a client-only effect) has not yet run.
-  let hydrated = $state(false);
-  $effect(() => {
-    hydrated = true;
-  });
-
-  // Lock body scroll while the scrim is present — including the fade-out outro, so
-  // the page can't scroll under a still-visible dimmer. We track the rendered scrim
-  // element rather than keying on `open`: the {#if open} block sets `scrimElement` on
-  // intro (bind:this) and clears it on a genuine close (guarded onoutroend), so the
-  // lock is held for the element's full visible lifetime. Counted lock — safe to
-  // nest with other overlays.
-  let scrimElement: HTMLElement | undefined = $state();
-  $effect(() => {
-    if (!scrimElement || !lockScroll) return;
-    const release = lockBodyScroll();
-    return release;
-  });
-</script>
-
-{#if hydrated && open}
-  <!--
-    The scrim itself is decorative chrome. With no children it is hidden from
-    assistive technology (aria-hidden). But when `children` are rendered — e.g. a
-    loading <Spinner role="status">"Loading…"</Spinner> — the wrapper must NOT be
-    aria-hidden, or that announced content is silenced for screen readers.
-  -->
-  <div
-    bind:this={scrimElement}
-    {...rest}
-    aria-hidden={children ? undefined : 'true'}
-    class={classNames('cinder-backdrop', invisible && 'cinder-backdrop--invisible', className)}
-    data-cinder-invisible={invisible ? '' : undefined}
-    {onclick}
-    transition:fade={{ duration: effectiveDuration }}
-    onoutroend={() => {
-      // Only clear on a genuine close. If `open` flipped back to true during the
-      // outro, a keyless {#if} reuses this node and cancels the outro — but guard
-      // against any late/zero-duration outro callback releasing the lock while the
-      // scrim is still open and visible.
-      if (!open) scrimElement = undefined;
-    }}
-  >
-    {#if children}
-      {@render children()}
-    {/if}
-  </div>
-{/if}

package/src/components/backdrop/backdrop.types.ts

@@ -1,30 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-
-export type BackdropProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'onclick'> & {
-  /** Whether the backdrop is visible and active. */
-  open: boolean;
-  /**
-   * When true the backdrop is transparent but still captures pointer events,
-   * enabling click-to-close without dimming content behind it.
-   * @default false
-   */
-  invisible?: boolean;
-  /**
-   * Lock body scroll while the backdrop is open (counted lock — safe to nest
-   * with other overlays). Set false when the consumer manages scrolling itself.
-   * @default true
-   */
-  lockScroll?: boolean;
-  /**
-   * Enter/leave animation duration in milliseconds. Collapses to 0 under
-   * `prefers-reduced-motion`. Overrides the default when provided.
-   */
-  transitionDuration?: number;
-  /** Click handler — use this to wire click-to-close on the scrim. */
-  onclick?: (event: MouseEvent) => void;
-  /** Additional class names merged onto the root element. */
-  class?: string;
-  /** Optional content rendered above the scrim (e.g. a Spinner for a loading state). */
-  children?: Snippet;
-};

package/src/components/backdrop/index.ts

@@ -1,6 +0,0 @@
-import './backdrop.css';
-import Backdrop from './backdrop.svelte';
-
-export default Backdrop;
-export type { BackdropProps } from './backdrop.types.ts';
-export { Backdrop };