@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/calendar/calendar.svelte

@@ -0,0 +1,308 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { tick, untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+const WEEKDAY_INDEXES = [0, 1, 2, 3, 4, 5, 6];
+let { id, value = $bindable(undefined), month, min, max, firstDayOfWeek = 0, locale = 'en-US', label = 'Calendar', disabled = false, class: className, onchange, disabledDate, ...rest } = $props();
+const generatedId = $props.id();
+const rootId = $derived(id ?? generatedId);
+const titleId = $derived(`${rootId}-title`);
+const monthGridId = $derived(`${rootId}-grid`);
+function parseISODate(iso) {
+    if (!iso)
+        return null;
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const monthValue = Number(match[2]);
+    const day = Number(match[3]);
+    if (monthValue < 1 || monthValue > 12)
+        return null;
+    const date = new Date(year, monthValue - 1, day);
+    if (date.getFullYear() !== year ||
+        date.getMonth() !== monthValue - 1 ||
+        date.getDate() !== day) {
+        return null;
+    }
+    return date;
+}
+function toISODate(date) {
+    const year = date.getFullYear();
+    const monthValue = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${monthValue}-${day}`;
+}
+function startOfMonth(date) {
+    return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+function addDays(date, days) {
+    const next = new Date(date);
+    next.setDate(next.getDate() + days);
+    return next;
+}
+function addMonths(date, months) {
+    return new Date(date.getFullYear(), date.getMonth() + months, 1);
+}
+function startOfWeek(date, weekStart) {
+    const offset = (date.getDay() - weekStart + 7) % 7;
+    return addDays(date, -offset);
+}
+function isISOWithinBounds(iso) {
+    if (min && iso < min)
+        return false;
+    if (max && iso > max)
+        return false;
+    return true;
+}
+function isDateDisabled(iso) {
+    if (!isISOWithinBounds(iso))
+        return true;
+    return disabledDate?.(iso) ?? false;
+}
+function resolveAnchorIso(valueProp, monthProp, fallbackIso) {
+    if (valueProp && parseISODate(valueProp))
+        return valueProp;
+    if (monthProp && parseISODate(monthProp))
+        return monthProp;
+    return fallbackIso;
+}
+const initialTodayIso = toISODate(new Date());
+const initialAnchorIso = untrack(() => resolveAnchorIso(value, month, initialTodayIso));
+const initialFocusedIso = untrack(() => value && parseISODate(value) ? value : initialAnchorIso);
+const todayIso = $derived(toISODate(new Date()));
+const anchorIso = $derived(resolveAnchorIso(value, month, todayIso));
+const anchorDate = $derived(parseISODate(anchorIso) ?? new Date());
+let visibleMonthDate = $state(startOfMonth(parseISODate(initialAnchorIso) ?? new Date()));
+let focusedIso = $state(initialFocusedIso);
+let lastSyncedAnchorIso = $state(initialAnchorIso);
+const focusedDayId = $derived(`${monthGridId}-day-${focusedIso}`);
+$effect(() => {
+    if (anchorIso === lastSyncedAnchorIso)
+        return;
+    visibleMonthDate = startOfMonth(anchorDate);
+    if (value)
+        focusedIso = value;
+    else
+        focusedIso = anchorIso;
+    lastSyncedAnchorIso = anchorIso;
+});
+const monthLabel = $derived(new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(visibleMonthDate));
+const weekdayLabels = $derived(WEEKDAY_INDEXES.map((index) => {
+    const dayIndex = (index + firstDayOfWeek) % 7;
+    const base = new Date(2024, 0, 7 + dayIndex);
+    return new Intl.DateTimeFormat(locale, { weekday: 'short' }).format(base);
+}));
+const cells = $derived.by(() => {
+    const first = startOfMonth(visibleMonthDate);
+    const gridStart = startOfWeek(first, firstDayOfWeek);
+    const selectedIso = value;
+    const focused = focusedIso;
+    const dayLabelFmt = new Intl.DateTimeFormat(locale, {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    });
+    const next = [];
+    for (let index = 0; index < 42; index += 1) {
+        const date = addDays(gridStart, index);
+        const iso = toISODate(date);
+        next.push({
+            iso,
+            day: date.getDate(),
+            inMonth: date.getMonth() === visibleMonthDate.getMonth(),
+            disabled: disabled || isDateDisabled(iso),
+            focused: iso === focused,
+            selected: iso === selectedIso,
+            ariaLabel: dayLabelFmt.format(date),
+        });
+    }
+    return next;
+});
+const rows = $derived.by(() => {
+    const next = [];
+    for (let index = 0; index < cells.length; index += 7) {
+        next.push(cells.slice(index, index + 7));
+    }
+    return next;
+});
+async function focusDate(iso, moveDomFocus = false) {
+    focusedIso = iso;
+    const parsed = parseISODate(iso);
+    if (parsed) {
+        visibleMonthDate = startOfMonth(parsed);
+    }
+    if (!moveDomFocus)
+        return;
+    await tick();
+    const target = document.getElementById(focusedDayId);
+    target?.focus();
+}
+function commitDate(iso) {
+    if (disabled || isDateDisabled(iso))
+        return;
+    value = iso;
+    focusedIso = iso;
+    onchange?.(iso);
+}
+async function moveFocusedByDays(delta) {
+    const base = parseISODate(focusedIso) ?? visibleMonthDate;
+    const next = addDays(base, delta);
+    await focusDate(toISODate(next), true);
+}
+function clampDayToMonth(year, monthValue, day) {
+    const lastDay = new Date(year, monthValue + 1, 0).getDate();
+    return new Date(year, monthValue, Math.min(day, lastDay));
+}
+async function moveFocusedByMonths(delta, moveDomFocus = true) {
+    const base = parseISODate(focusedIso) ?? visibleMonthDate;
+    const monthStart = addMonths(startOfMonth(base), delta);
+    const candidate = clampDayToMonth(monthStart.getFullYear(), monthStart.getMonth(), base.getDate());
+    await focusDate(toISODate(candidate), moveDomFocus);
+}
+async function handleKeydown(event) {
+    if (disabled)
+        return;
+    switch (event.key) {
+        case 'ArrowLeft':
+            event.preventDefault();
+            await moveFocusedByDays(-1);
+            break;
+        case 'ArrowRight':
+            event.preventDefault();
+            await moveFocusedByDays(1);
+            break;
+        case 'ArrowUp':
+            event.preventDefault();
+            await moveFocusedByDays(-7);
+            break;
+        case 'ArrowDown':
+            event.preventDefault();
+            await moveFocusedByDays(7);
+            break;
+        case 'Home': {
+            event.preventDefault();
+            const focused = parseISODate(focusedIso) ?? visibleMonthDate;
+            const weekStart = startOfWeek(focused, firstDayOfWeek);
+            await focusDate(toISODate(weekStart), true);
+            break;
+        }
+        case 'End': {
+            event.preventDefault();
+            const focused = parseISODate(focusedIso) ?? visibleMonthDate;
+            const weekEnd = addDays(startOfWeek(focused, firstDayOfWeek), 6);
+            await focusDate(toISODate(weekEnd), true);
+            break;
+        }
+        case 'PageUp':
+            event.preventDefault();
+            await moveFocusedByMonths(-1);
+            break;
+        case 'PageDown':
+            event.preventDefault();
+            await moveFocusedByMonths(1);
+            break;
+        case 'Enter':
+        case ' ':
+            event.preventDefault();
+            commitDate(focusedIso);
+            break;
+        default:
+            break;
+    }
+}
+function canGoPrevMonth() {
+    if (!min)
+        return true;
+    const prev = addMonths(visibleMonthDate, -1);
+    const monthEnd = new Date(prev.getFullYear(), prev.getMonth() + 1, 0);
+    return toISODate(monthEnd) >= min;
+}
+function canGoNextMonth() {
+    if (!max)
+        return true;
+    const next = addMonths(visibleMonthDate, 1);
+    const monthStart = new Date(next.getFullYear(), next.getMonth(), 1);
+    return toISODate(monthStart) <= max;
+}
+</script>
+
+<div {...rest} aria-label={label} class={classNames('cinder-calendar', className)}>
+  <div class="cinder-calendar__header">
+    <button
+      type="button"
+      class="cinder-calendar__nav"
+      aria-label="Previous month"
+      onclick={() => {
+        void moveFocusedByMonths(-1, false);
+      }}
+      disabled={disabled || !canGoPrevMonth()}
+    >
+      ‹
+    </button>
+    <p id={titleId} class="cinder-calendar__title">{monthLabel}</p>
+    <button
+      type="button"
+      class="cinder-calendar__nav"
+      aria-label="Next month"
+      onclick={() => {
+        void moveFocusedByMonths(1, false);
+      }}
+      disabled={disabled || !canGoNextMonth()}
+    >
+      ›
+    </button>
+  </div>
+
+  <div class="cinder-calendar__weekdays" aria-hidden="true">
+    {#each weekdayLabels as weekday (weekday)}
+      <span class="cinder-calendar__weekday">{weekday}</span>
+    {/each}
+  </div>
+
+  <div
+    id={monthGridId}
+    class="cinder-calendar__grid"
+    role="grid"
+    aria-labelledby={titleId}
+    tabindex="-1"
+    onkeydown={handleKeydown}
+  >
+    {#each rows as row, rowIndex (row[0]?.iso ?? rowIndex)}
+      <div role="row" class="cinder-calendar__grid-row">
+        {#each row as cell (cell.iso)}
+          <div
+            role="gridcell"
+            aria-selected={cell.selected || undefined}
+            class="cinder-calendar__gridcell"
+          >
+            <button
+              type="button"
+              id={`${monthGridId}-day-${cell.iso}`}
+              class="cinder-calendar__day"
+              data-outside={cell.inMonth ? undefined : ''}
+              data-selected={cell.selected ? '' : undefined}
+              data-focused={cell.focused ? '' : undefined}
+              aria-current={cell.iso === todayIso ? 'date' : undefined}
+              aria-label={cell.ariaLabel}
+              aria-disabled={cell.disabled ? 'true' : undefined}
+              tabindex={cell.focused ? 0 : -1}
+              onclick={() => {
+                commitDate(cell.iso);
+              }}
+              onfocus={() => {
+                focusedIso = cell.iso;
+              }}
+            >
+              {cell.day}
+            </button>
+          </div>
+        {/each}
+      </div>
+    {/each}
+  </div>
+</div>

package/src/components/calendar/calendar.types.ts

@@ -0,0 +1,31 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type CalendarProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'onchange'
+> & {
+  /** Optional root id. */
+  id?: string;
+  /** Selected ISO date (`YYYY-MM-DD`). Bindable. */
+  value?: string | undefined;
+  /** Visible month anchor (`YYYY-MM-DD`), defaults to selected date or today. */
+  month?: string | undefined;
+  /** Earliest selectable day (`YYYY-MM-DD`). */
+  min?: string | undefined;
+  /** Latest selectable day (`YYYY-MM-DD`). */
+  max?: string | undefined;
+  /** First weekday index, `0` Sunday to `6` Saturday. Defaults to `0`. */
+  firstDayOfWeek?: number;
+  /** Localized month label locale. Defaults to `en-US`. */
+  locale?: string;
+  /** Accessible label for the grid. Defaults to `Calendar`. */
+  label?: string;
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Additional classes for the root node. */
+  class?: string;
+  /** Called when the user commits a day selection. */
+  onchange?: (value: string) => void;
+  /** Return true to disable a specific day. */
+  disabledDate?: (value: string) => boolean;
+};

package/src/components/calendar/calendar.variables.ts

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

package/src/components/calendar/index.ts

@@ -0,0 +1,6 @@
+import './calendar.css';
+import Calendar from './calendar.svelte';
+
+export default Calendar;
+export type { CalendarProps } from './calendar.types.ts';
+export { Calendar };

package/src/components/callout/callout.schema.ts

@@ -0,0 +1,46 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    title: {
+      type: 'string',
+      description:
+        'Optional title rendered as a `<p class="cinder-callout__title">`.\n\nRendered as a paragraph rather than a heading element so the\ncallout does not inject an entry into the document outline. If a\ncallout genuinely participates in the outline (e.g. it titles a\nstandalone section), wrap it in a `<section>` with its own heading\nrather than promoting this prop to `<h*>`.\n\nWhen supplied and no `aria-label` or `aria-labelledby` is passed\non rest props, the title also becomes the `aria-label` of the\nroot element so the landmark or note has an accessible name.',
+    },
+    variant: {
+      enum: ['info', 'success', 'warning', 'danger'],
+      description: "Visual + semantic variant. Default `'info'`.",
+    },
+    semantic: {
+      enum: ['aside', 'note'],
+      description:
+        "Root semantics. Default `'aside'`; use `'note'` for static note semantics without a complementary landmark.",
+    },
+    class: {
+      type: 'string',
+      description:
+        'Extra classes appended to the root element. Pass via the explicit\n`class` prop — it is excluded from rest-prop spread, so writing\n`class="x"` inside spread attributes will not reach the root.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Callout body content.',
+      },
+      {
+        name: 'icon',
+        reason: 'function-or-snippet',
+        description:
+          'Optional decorative icon rendered inside an `aria-hidden` wrapper.\n\nThe icon is a second visual channel alongside variant color — it\nhelps satisfy WCAG 1.4.1 (Use of Color) by ensuring the variant is\nconveyed by more than color alone. The accessible meaning still\nlives in `title` and/or `children`; the icon must not be the only\ncarrier of information.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/callout/callout.svelte

@@ -0,0 +1,78 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { variant = 'info', semantic = 'aside', title, icon, class: className, children, ...rest } = $props();
+// Strip role + live-region attributes from rest props. The type
+// already omits these, but a consumer can escape the type system
+// (`as never`, spread from an `unknown` source). Scrubbing at runtime
+// guarantees the hard invariant that a callout is never announced as
+// a live region and never overrides the component-owned root role.
+// Mirrors banner.svelte's defense-in-depth pattern.
+const restWithoutForbidden = $derived.by(() => {
+    const { role: _role, 'aria-live': _ariaLive, 'aria-atomic': _ariaAtomic, 'aria-relevant': _ariaRelevant, 'aria-busy': _ariaBusy, ...filtered } = rest;
+    return filtered;
+});
+// Derive an accessible name for the root so an aside callout that lands at
+// landmark level is not an unnamed `complementary` landmark, and a note mode
+// callout has the expected note name. Priority mirrors banner.svelte:
+// consumer `aria-labelledby` > consumer `aria-label` > `title`.
+const ariaLabel = $derived(rest['aria-labelledby'] ? undefined : (rest['aria-label'] ?? title));
+</script>
+
+{#if semantic === 'note'}
+  <div
+    {...restWithoutForbidden}
+    class={classNames(
+      'cinder-callout',
+      'cinder-_status-surface',
+      'cinder-_status-surface-border',
+      'cinder-_status-surface-stripe',
+      className,
+    )}
+    data-cinder-variant={variant}
+    role="note"
+    aria-label={ariaLabel}
+  >
+    {#if icon}
+      <div class="cinder-callout__icon" aria-hidden="true">
+        {@render icon()}
+      </div>
+    {/if}
+
+    <div class="cinder-callout__content">
+      {#if title}
+        <p class="cinder-callout__title">{title}</p>
+      {/if}
+      {@render children()}
+    </div>
+  </div>
+{:else}
+  <aside
+    {...restWithoutForbidden}
+    class={classNames(
+      'cinder-callout',
+      'cinder-_status-surface',
+      'cinder-_status-surface-border',
+      'cinder-_status-surface-stripe',
+      className,
+    )}
+    data-cinder-variant={variant}
+    aria-label={ariaLabel}
+  >
+    {#if icon}
+      <div class="cinder-callout__icon" aria-hidden="true">
+        {@render icon()}
+      </div>
+    {/if}
+
+    <div class="cinder-callout__content">
+      {#if title}
+        <p class="cinder-callout__title">{title}</p>
+      {/if}
+      {@render children()}
+    </div>
+  </aside>
+{/if}

package/src/components/callout/callout.types.ts

@@ -0,0 +1,92 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * Visual + semantic variants for {@link Callout}.
+ *
+ * Matches `banner.svelte` so both components draw from the same semantic
+ * tokens (`--cinder-info`, `--cinder-success`, `--cinder-warning`,
+ * `--cinder-danger`). `alert.svelte` uses `error` instead of `danger`;
+ * that divergence is tracked in `banner.a11y.md`.
+ */
+export type CalloutVariant = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Root semantics for {@link Callout}.
+ *
+ * - `'aside'` keeps the historical `<aside>` behavior and may expose a
+ *   `complementary` landmark depending on where the callout is placed.
+ * - `'note'` renders a static `<div role="note">` for explanatory notes that
+ *   should not appear in landmark navigation.
+ */
+export type CalloutSemantic = 'aside' | 'note';
+/**
+ * Props for the {@link Callout} component — an inline admonition block
+ * for documentation and long-form content. See `callout.a11y.md` for
+ * the full accessibility model.
+ *
+ * Callout is the static, prose-embedded sibling of:
+ *
+ * - `banner.svelte` — page-level, dismissible, `role="region"` landmark.
+ * - `alert.svelte` — dynamic notification with `role="alert"` that
+ *   announces to assistive tech when it appears or updates. Use that
+ *   component when the message is added to the page in response to a
+ *   user action and screen-reader users need to be notified.
+ *
+ * Callout is intentionally **not** a live region. It is static content
+ * rendered as part of the document, analogous to Markdown admonitions
+ * (note / tip / warning / danger). Use `semantic="note"` when the visual
+ * surface should expose `role="note"` instead of an `<aside>`. The type omits
+ * `role`, `aria-live`, `aria-atomic`, `aria-relevant`, and `aria-busy` from
+ * the underlying `HTMLAttributes` so a consumer cannot silently turn a
+ * callout into an alert/status live region or arbitrary landmark. The runtime
+ * also scrubs those attributes from rest props for defense in depth — see
+ * banner.svelte for the analogous pattern.
+ *
+ * The default root is `<aside>`. When placed directly inside `<body>`,
+ * `<main>`, or another sectioning landmark, `<aside>` is exposed as a
+ * `complementary` landmark; inside `<article>` or `<section>` the landmark
+ * role is suppressed and the element behaves as generic sectioning content.
+ * When the callout lands at landmark level, supply `title` (used as the
+ * accessible name) or pass `aria-label` / `aria-labelledby` so the landmark
+ * has a meaningful name.
+ */
+export type CalloutProps = Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'class' | 'role' | 'aria-live' | 'aria-atomic' | 'aria-relevant' | 'aria-busy'
+> & {
+  /** Visual + semantic variant. Default `'info'`. */
+  variant?: CalloutVariant;
+  /** Root semantics. Default `'aside'`; use `'note'` for static note semantics without a complementary landmark. */
+  semantic?: CalloutSemantic;
+  /**
+   * Optional title rendered as a `<p class="cinder-callout__title">`.
+   *
+   * Rendered as a paragraph rather than a heading element so the
+   * callout does not inject an entry into the document outline. If a
+   * callout genuinely participates in the outline (e.g. it titles a
+   * standalone section), wrap it in a `<section>` with its own heading
+   * rather than promoting this prop to `<h*>`.
+   *
+   * When supplied and no `aria-label` or `aria-labelledby` is passed
+   * on rest props, the title also becomes the `aria-label` of the
+   * root element so the landmark or note has an accessible name.
+   */
+  title?: string;
+  /**
+   * Optional decorative icon rendered inside an `aria-hidden` wrapper.
+   *
+   * The icon is a second visual channel alongside variant color — it
+   * helps satisfy WCAG 1.4.1 (Use of Color) by ensuring the variant is
+   * conveyed by more than color alone. The accessible meaning still
+   * lives in `title` and/or `children`; the icon must not be the only
+   * carrier of information.
+   */
+  icon?: Snippet;
+  /** Callout body content. */
+  children: Snippet;
+  /**
+   * Extra classes appended to the root element. Pass via the explicit
+   * `class` prop — it is excluded from rest-prop spread, so writing
+   * `class="x"` inside spread attributes will not reach the root.
+   */
+  class?: string;
+};

package/src/components/callout/callout.variables.ts

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

package/src/components/callout/index.ts

@@ -0,0 +1,6 @@
+import './callout.css';
+import Callout from './callout.svelte';
+
+export default Callout;
+export type { CalloutProps, CalloutSemantic, CalloutVariant } from './callout.types.ts';
+export { Callout };

package/src/components/capability-gate/capability-gate.schema.ts

@@ -0,0 +1,76 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    feature: {
+      type: 'string',
+      description: 'The feature being gated.',
+    },
+    state: {
+      enum: [
+        'supported',
+        'unsupported',
+        'permission-needed',
+        'permission-denied',
+        'loading',
+        'unavailable',
+      ],
+      description: 'Current availability state.',
+    },
+    variant: {
+      enum: ['inline', 'banner', 'callout'],
+      description: 'Presentation variant.',
+      default: 'inline',
+    },
+    primaryAction: {
+      type: 'string',
+      description: 'Label for the primary action button.',
+    },
+    fallbackAction: {
+      type: 'string',
+      description: 'Label for the fallback action.',
+    },
+    fallbackHref: {
+      type: 'string',
+      description: 'Href for a fallback link.',
+    },
+    dismissAction: {
+      type: 'string',
+      description: 'Label for the dismiss action.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-capability-gate`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['feature', 'state'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        description: 'Custom content rendered below the status text and before the actions.',
+      },
+      {
+        name: 'ondismiss',
+        reason: 'function-or-snippet',
+        description: 'Called when the gate is dismissed.',
+      },
+      {
+        name: 'onfallbackaction',
+        reason: 'function-or-snippet',
+        description: 'Called when the fallback action button is activated.',
+      },
+      {
+        name: 'onprimaryaction',
+        reason: 'function-or-snippet',
+        description: 'Called when the primary action button is activated.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;