@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/avatar/avatar.schema.ts

@@ -0,0 +1,41 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    src: {
+      type: 'string',
+      description: 'Image source. When omitted, the initials fallback renders.',
+    },
+    alt: {
+      type: 'string',
+      description: 'Alternative text for the image. Defaults to `name` when present.',
+    },
+    name: {
+      type: 'string',
+      description:
+        'Display name used to compute initials when no image is available.\nAlso used as the default `alt` for the image.',
+    },
+    size: {
+      enum: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Size token. Default `md`.',
+    },
+    shape: {
+      enum: ['circle', 'square'],
+      description: 'Shape. Default `circle`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'class',
+        reason: 'unknown-shape',
+        description: 'Additional class names merged with `.cinder-avatar`.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/avatar/avatar.svelte

@@ -0,0 +1,48 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="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 } = $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(null);
+const showImage = $derived(!!src && failedSource !== src);
+const accessibleAlt = $derived(alt ?? name ?? '');
+const initials = $derived(computeInitials(name));
+function computeInitials(value) {
+    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

@@ -0,0 +1,33 @@
+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/avatar.variables.ts

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

package/src/components/avatar/index.ts

@@ -0,0 +1,6 @@
+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.schema.ts

@@ -0,0 +1,74 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    avatars: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            description: 'Stable identifier recommended for dynamic collaborator lists.',
+          },
+          name: {
+            type: 'string',
+            description: 'Display name used for initials, tooltip text, and accessible naming.',
+          },
+          src: {
+            type: 'string',
+            description: 'Optional avatar image source.',
+          },
+        },
+        additionalProperties: false,
+        required: ['name'],
+      },
+      description: 'Collaborators to render in the stack.',
+    },
+    label: {
+      type: 'string',
+      description: 'Accessible name for the avatar stack list.',
+      default: 'Collaborators',
+    },
+    maxVisible: {
+      type: 'number',
+      description: 'Maximum visible avatars before overflow.',
+      default: 5,
+    },
+    overlap: {
+      type: 'string',
+      description:
+        'Non-negative CSS length token for the amount each item overlaps its predecessor.',
+      default: '0.75rem',
+    },
+    zOrder: {
+      enum: ['first-on-top', 'last-on-top'],
+      description: 'Stacking order for visible avatars.',
+      default: 'last-on-top',
+    },
+    size: {
+      enum: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Size token forwarded to each visible Avatar.',
+      default: 'md',
+    },
+    shape: {
+      enum: ['circle', 'square'],
+      description: 'Shape forwarded to each visible Avatar.',
+      default: 'circle',
+    },
+    overflowLabel: {
+      type: 'string',
+      description: 'Accessible label for the overflow indicator.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-avatar-group`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['avatars'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,138 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="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 } = $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) {
+    if (!Number.isFinite(value))
+        return defaultMaxVisible;
+    return Math.max(0, Math.floor(value));
+}
+function normalizeOverlap(value) {
+    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) {
+    const counts = new Map();
+    for (const avatar of items) {
+        const identity = avatar.id ?? avatar.name ?? '';
+        counts.set(identity, (counts.get(identity) ?? 0) + 1);
+    }
+    return counts;
+}
+function getAvatarKey(avatar, index, counts) {
+    const identity = avatar.id ?? avatar.name ?? '';
+    return counts.get(identity) === 1 ? identity : `${identity}:${index}`;
+}
+function getVisibleStackIndex(index, count, order) {
+    if (order === 'first-on-top')
+        return count - index;
+    return index + 1;
+}
+function getOverflowStackIndex(count, order) {
+    if (count === 0)
+        return 0;
+    if (order === 'first-on-top')
+        return 0;
+    return count + 1;
+}
+function avatarSourceProps(src) {
+    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

@@ -0,0 +1,97 @@
+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/avatar-group.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = ['--cinder-avatar-group-overlap'];
+
+export default variables;

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

@@ -0,0 +1,6 @@
+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.schema.ts

@@ -0,0 +1,52 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    open: {
+      type: 'boolean',
+      description: 'Whether the backdrop is visible and active.',
+    },
+    invisible: {
+      type: 'boolean',
+      description:
+        'When true the backdrop is transparent but still captures pointer events,\nenabling click-to-close without dimming content behind it.',
+      default: false,
+    },
+    lockScroll: {
+      type: 'boolean',
+      description:
+        'Lock body scroll while the backdrop is open (counted lock — safe to nest\nwith other overlays). Set false when the consumer manages scrolling itself.',
+      default: true,
+    },
+    transitionDuration: {
+      type: 'number',
+      description:
+        'Enter/leave animation duration in milliseconds. Collapses to 0 under\n`prefers-reduced-motion`. Overrides the default when provided.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged onto the root element.',
+    },
+  },
+  additionalProperties: false,
+  required: ['open'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        description:
+          'Optional content rendered above the scrim (e.g. a Spinner for a loading state).',
+      },
+      {
+        name: 'onclick',
+        reason: 'function-or-snippet',
+        description: 'Click handler — use this to wire click-to-close on the scrim.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/backdrop/backdrop.svelte

@@ -0,0 +1,80 @@
+<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
+ */
+export {};
+</script>
+
+<script lang="ts">
+import { fade } from 'svelte/transition';
+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 } = $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 = $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

@@ -0,0 +1,30 @@
+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/backdrop.variables.ts

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

package/src/components/backdrop/index.ts

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