@lostgradient/cinder 0.4.0 → 0.5.0

package/src/components/date-picker/date-picker.css

@@ -0,0 +1,106 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@import '../calendar/calendar.css';
+
+@layer cinder.components {
+  .cinder-date-picker {
+    display: grid;
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-date-picker__label {
+    display: block;
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text);
+  }
+
+  .cinder-date-picker__control {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    align-items: center;
+    min-height: 2.25rem;
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    background: var(--cinder-surface-raised);
+  }
+
+  .cinder-date-picker__control[data-invalid] {
+    border-color: var(--cinder-danger);
+  }
+
+  .cinder-date-picker__input {
+    inline-size: 100%;
+    min-inline-size: 0;
+    border: 0;
+    background: transparent;
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-sm);
+    padding: var(--cinder-space-1-5) var(--cinder-space-2);
+  }
+
+  .cinder-date-picker__input:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  .cinder-date-picker__trigger {
+    appearance: none;
+    border: 0;
+    border-inline-start: 1px solid var(--cinder-border);
+    background: transparent;
+    color: var(--cinder-text-muted);
+    block-size: 100%;
+    inline-size: 2.25rem;
+    cursor: pointer;
+  }
+
+  .cinder-date-picker__trigger:disabled {
+    cursor: not-allowed;
+    color: var(--cinder-text-disabled);
+  }
+
+  .cinder-date-picker__panel {
+    display: grid;
+    gap: var(--cinder-space-2);
+    min-inline-size: 16rem;
+  }
+
+  .cinder-date-picker__time {
+    display: grid;
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-date-picker__time-label {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-date-picker__time-input {
+    min-height: 2rem;
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-sm);
+    background: var(--cinder-surface-raised);
+    color: var(--cinder-text);
+    padding: var(--cinder-space-1) var(--cinder-space-2);
+  }
+
+  .cinder-date-picker__description {
+    margin: 0;
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-date-picker__error {
+    margin: 0;
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-danger);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-date-picker__input:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 2px;
+      box-shadow: none;
+    }
+  }
+}

package/src/components/date-picker/date-picker.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "date-picker",
+  "import": "@lostgradient/cinder/date-picker",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic date picker",
+      "description": "Single-date picker with a custom calendar popover.",
+      "code": "<script lang=\"ts\">\n  import { DatePicker } from '@lostgradient/cinder/date-picker';\n\n  let value = $state<string | undefined>('2026-06-29');\n</script>\n\n<div style=\"display: grid; gap: 0.75rem; max-inline-size: 22rem;\">\n  <DatePicker id=\"basic-date-picker\" bind:value label=\"Event date\" />\n  <code>{value ?? 'undefined'}</code>\n</div>\n"
+    },
+    {
+      "id": "date-time",
+      "title": "Date-time picker",
+      "description": "Calendar selection plus time input for minute-level granularity.",
+      "code": "<script lang=\"ts\">\n  import { DatePicker } from '@lostgradient/cinder/date-picker';\n\n  let value = $state<string | undefined>('2026-06-29T09:30');\n</script>\n\n<div style=\"display: grid; gap: 0.75rem; max-inline-size: 22rem;\">\n  <DatePicker\n    id=\"date-time-picker\"\n    bind:value\n    granularity=\"minute\"\n    label=\"Scheduled at\"\n    min=\"2026-06-01T00:00\"\n    max=\"2026-12-31T23:59\"\n  />\n  <code>{value ?? 'undefined'}</code>\n</div>\n"
+    }
+  ]
+}

package/src/components/date-picker/date-picker.svelte

@@ -0,0 +1,243 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status alpha
+   * @purpose Controlled date picker that combines a text trigger, floating calendar grid, and optional time controls.
+   * @tag form
+   * @tag date
+   * @tag calendar
+   * @useWhen Collecting a date with consistent cross-browser UI and keyboard support.
+   * @useWhen Collecting local datetime values while keeping ISO strings as the controlled model.
+   * @avoidWhen Browser-native date controls are acceptable and custom styling is unnecessary.
+   * @related calendar, date-range-field, popover
+   */
+  export type { DatePickerGranularity, DatePickerProps } from './date-picker.types.ts';
+</script>
+
+<script lang="ts">
+  import type { DatePickerGranularity, DatePickerProps } from './date-picker.types.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import Calendar from '../calendar/calendar.svelte';
+  import Popover from '../popover/popover.svelte';
+
+  let {
+    id,
+    value = $bindable<string | undefined>(undefined),
+    label,
+    placeholder = 'YYYY-MM-DD',
+    granularity = 'day',
+    min,
+    max,
+    description,
+    error,
+    disabled = false,
+    class: className,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    onchange,
+    ...rest
+  }: DatePickerProps = $props();
+
+  let open = $state(false);
+  let inputElement = $state<HTMLInputElement | null>(null);
+  let triggerElement = $state<HTMLButtonElement | null>(null);
+
+  function isLeapYear(year: number): boolean {
+    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  }
+
+  function daysInMonth(year: number, month: number): number {
+    if (month === 2) return isLeapYear(year) ? 29 : 28;
+    if ([4, 6, 9, 11].includes(month)) return 30;
+    return 31;
+  }
+
+  function isValidDatePart(datePart: string): boolean {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(datePart);
+    if (!match) return false;
+    const [, rawYear, rawMonth, rawDay] = match;
+    const year = Number(rawYear);
+    const monthValue = Number(rawMonth);
+    const day = Number(rawDay);
+    return monthValue >= 1 && monthValue <= 12 && day >= 1 && day <= daysInMonth(year, monthValue);
+  }
+
+  function isValidTimePart(timePart: string): boolean {
+    const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(timePart);
+    if (!match) return false;
+    const [, rawHour, rawMinute, rawSecond = '00'] = match;
+    const hour = Number(rawHour);
+    const minute = Number(rawMinute);
+    const second = Number(rawSecond);
+    return hour <= 23 && minute <= 59 && second <= 59;
+  }
+
+  function normalizeValue(
+    nextValue: string | undefined,
+    nextGranularity: DatePickerGranularity,
+  ): string | undefined {
+    if (!nextValue) return undefined;
+    const datePart = nextValue.slice(0, 10);
+    if (!isValidDatePart(datePart)) return undefined;
+    if (nextGranularity === 'day') return datePart;
+    const timePart =
+      nextValue.length === 10 ? '00:00' : nextValue[10] === 'T' ? nextValue.slice(11) : undefined;
+    if (!timePart || !isValidTimePart(timePart)) return undefined;
+    const [rawHour = '00', rawMinute = '00', rawSecond = '00'] = timePart.split(':');
+    const hour = rawHour.padStart(2, '0').slice(0, 2);
+    const minute = rawMinute.padStart(2, '0').slice(0, 2);
+    const second = rawSecond.padStart(2, '0').slice(0, 2);
+    if (nextGranularity === 'hour') return `${datePart}T${hour}:00`;
+    if (nextGranularity === 'minute') return `${datePart}T${hour}:${minute}`;
+    return `${datePart}T${hour}:${minute}:${second}`;
+  }
+
+  const normalizedValue = $derived(normalizeValue(value, granularity));
+  const normalizedMin = $derived(normalizeValue(min, granularity));
+  const normalizedMax = $derived(normalizeValue(max, granularity));
+  const selectedDate = $derived(normalizedValue?.slice(0, 10));
+  const selectedTime = $derived(
+    granularity === 'day'
+      ? undefined
+      : (normalizedValue?.slice(11) ??
+          (granularity === 'second' ? '00:00:00' : granularity === 'minute' ? '00:00' : '00:00')),
+  );
+  const step = $derived(granularity === 'second' ? 1 : granularity === 'minute' ? 60 : 3600);
+  const inputType = $derived(granularity === 'day' ? 'date' : 'datetime-local');
+  const invalid = $derived(error ? 'true' : ariaInvalid === true || ariaInvalid === 'true' ? 'true' : undefined);
+  const describedById = $derived(
+    [
+      ariaDescribedBy,
+      description ? `${id}-description` : undefined,
+      error ? `${id}-error` : undefined,
+    ]
+      .filter(Boolean)
+      .join(' ') || undefined,
+  );
+
+  $effect(() => {
+    if (value === normalizedValue) return;
+    value = normalizedValue;
+  });
+
+  function emit(next: string | undefined) {
+    value = next;
+    onchange?.(next);
+  }
+
+  function clampToBounds(next: string | undefined): string | undefined {
+    if (!next) return undefined;
+    if (normalizedMin && next < normalizedMin) return normalizedMin;
+    if (normalizedMax && next > normalizedMax) return normalizedMax;
+    return next;
+  }
+
+  function handleCalendarChange(nextDate: string) {
+    if (granularity === 'day') {
+      emit(clampToBounds(nextDate));
+      open = false;
+      return;
+    }
+    const existingTime = selectedTime ?? (granularity === 'second' ? '00:00:00' : '00:00');
+    emit(clampToBounds(normalizeValue(`${nextDate}T${existingTime}`, granularity)));
+  }
+
+  function handleTimeChange(event: Event) {
+    const target = event.currentTarget as HTMLInputElement;
+    if (!selectedDate) return;
+    emit(clampToBounds(normalizeValue(`${selectedDate}T${target.value}`, granularity)));
+  }
+
+  function handleInputChange(event: Event) {
+    const target = event.currentTarget as HTMLInputElement;
+    emit(clampToBounds(normalizeValue(target.value, granularity)));
+  }
+
+  const timeMin = $derived.by(() => {
+    if (granularity === 'day' || !selectedDate || !normalizedMin) return undefined;
+    if (!normalizedMin.startsWith(`${selectedDate}T`)) return undefined;
+    return normalizedMin.slice(11);
+  });
+  const timeMax = $derived.by(() => {
+    if (granularity === 'day' || !selectedDate || !normalizedMax) return undefined;
+    if (!normalizedMax.startsWith(`${selectedDate}T`)) return undefined;
+    return normalizedMax.slice(11);
+  });
+</script>
+
+<div {...rest} class={classNames('cinder-date-picker', className)}>
+  {#if label}
+    <label class="cinder-date-picker__label" for={id}>{label}</label>
+  {/if}
+
+  <div class="cinder-date-picker__control" data-invalid={invalid ? '' : undefined}>
+    <input
+      bind:this={inputElement}
+      class="cinder-date-picker__input"
+      {id}
+      type={inputType}
+      value={normalizedValue ?? ''}
+      min={normalizedMin}
+      max={normalizedMax}
+      step={granularity === 'day' ? undefined : step}
+      {placeholder}
+      {disabled}
+      aria-invalid={invalid}
+      aria-describedby={describedById}
+      onchange={handleInputChange}
+    />
+    <button
+      bind:this={triggerElement}
+      type="button"
+      class="cinder-date-picker__trigger"
+      aria-label={label ? `Open ${label} calendar` : 'Open date picker'}
+      {disabled}
+      onclick={() => {
+        if (!disabled) open = true;
+      }}
+    >
+      Open
+    </button>
+  </div>
+
+  <Popover
+    bind:open
+    triggerRef={triggerElement ?? inputElement}
+    role="dialog"
+    label={label ? `${label} calendar` : 'Date picker calendar'}
+    focusManagement="preserve"
+    widthMode="content"
+    class="cinder-date-picker__panel"
+  >
+    <Calendar
+      value={selectedDate}
+      min={normalizedMin?.slice(0, 10)}
+      max={normalizedMax?.slice(0, 10)}
+      onchange={handleCalendarChange}
+      {disabled}
+    />
+    {#if granularity !== 'day'}
+      <div class="cinder-date-picker__time">
+        <span class="cinder-date-picker__time-label">Time</span>
+        <input
+          class="cinder-date-picker__time-input"
+          type="time"
+          {step}
+          value={selectedTime}
+          min={timeMin}
+          max={timeMax}
+          disabled={disabled || !selectedDate}
+          onchange={handleTimeChange}
+        />
+      </div>
+    {/if}
+  </Popover>
+
+  {#if description}
+    <p id={`${id}-description`} class="cinder-date-picker__description">{description}</p>
+  {/if}
+  {#if error}
+    <p id={`${id}-error`} class="cinder-date-picker__error" aria-live="polite">{error}</p>
+  {/if}
+</div>

package/src/components/date-picker/date-picker.types.ts

@@ -0,0 +1,33 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type DatePickerGranularity = 'day' | 'hour' | 'minute' | 'second';
+
+export type DatePickerProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'onchange'
+> & {
+  /** Stable id for label/input/error wiring. */
+  id: string;
+  /** Controlled value as local ISO string. Bindable. */
+  value?: string | undefined;
+  /** Field label text. */
+  label?: string;
+  /** Placeholder shown when empty. */
+  placeholder?: string;
+  /** Date-time precision. Defaults to day. */
+  granularity?: DatePickerGranularity;
+  /** Minimum allowed value (same format as `value`). */
+  min?: string | undefined;
+  /** Maximum allowed value (same format as `value`). */
+  max?: string | undefined;
+  /** Optional helper text. */
+  description?: string;
+  /** Optional validation error text. */
+  error?: string;
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Additional classes for the root. */
+  class?: string;
+  /** Called when the value changes. */
+  onchange?: (value: string | undefined) => void;
+};

package/src/components/date-picker/index.ts

@@ -0,0 +1,6 @@
+import './date-picker.css';
+import DatePicker from './date-picker.svelte';
+
+export default DatePicker;
+export type { DatePickerGranularity, DatePickerProps } from './date-picker.types.ts';
+export { DatePicker };

package/src/components/date-range-field/date-range-field.css

@@ -1,4 +1,5 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@import '../date-picker/date-picker.css';
 
 @layer cinder.components {
   /* ========================================

package/src/components/date-range-field/date-range-field.svelte

@@ -29,8 +29,8 @@
     DateRangeValue,
   } from './date-range-field.types.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import DatePicker from '../date-picker/date-picker.svelte';
   import {
-    ariaInvalid,
     composeDescribedBy,
     describeId,
     errorId as buildErrorId,
@@ -194,17 +194,6 @@
     return left.start === right.start && left.end === right.end;
   }
 
-  function inputTypeFor(nextGranularity: DateRangeGranularity): 'date' | 'datetime-local' {
-    return nextGranularity === 'day' ? 'date' : 'datetime-local';
-  }
-
-  function inputStepFor(nextGranularity: DateRangeGranularity): number | undefined {
-    if (nextGranularity === 'hour') return 3600;
-    if (nextGranularity === 'minute') return 60;
-    if (nextGranularity === 'second') return 1;
-    return undefined;
-  }
-
   function isLeapYear(year: number): boolean {
     return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
   }
@@ -266,8 +255,6 @@
     };
   }
 
-  const inputType = $derived(inputTypeFor(granularity));
-  const inputStep = $derived(inputStepFor(granularity));
   const normalizedValue = $derived(normalizeDateRangeValue(value, granularity));
 
   $effect(() => {
@@ -291,11 +278,10 @@
     onchange?.(next);
   }
 
-  function handleStartChange(event: Event) {
-    const target = event.target as HTMLInputElement;
+  function handleStartChange(nextStart: string | undefined) {
     const next = normalizeDateRangeValue(
       {
-        start: target.value,
+        start: nextStart,
         end: value.end,
       },
       granularity,
@@ -305,12 +291,11 @@
     onchange?.(next);
   }
 
-  function handleEndChange(event: Event) {
-    const target = event.target as HTMLInputElement;
+  function handleEndChange(nextEnd: string | undefined) {
     const next = normalizeDateRangeValue(
       {
         start: value.start,
-        end: target.value,
+        end: nextEnd,
       },
       granularity,
     );
@@ -320,7 +305,6 @@
   }
 
   const hasError = $derived(!!error);
-  const invalid = $derived(ariaInvalid(hasError));
 </script>
 
 <div
@@ -328,6 +312,7 @@
   class={classNames('cinder-date-range-field', className)}
   role="group"
   aria-labelledby={legendId}
+  aria-describedby={describedBy}
 >
   {#if label}
     <p id={legendId} class="cinder-date-range-field__legend" data-disabled={disabled || undefined}>
@@ -365,17 +350,16 @@
       >
         {resolvedStartLabel}
       </label>
-      <input
+      <DatePicker
         id={startId}
-        type={inputType}
-        class="cinder-date-range-field__date-input"
-        value={normalizedValue.start ?? ''}
+        class="cinder-date-range-field__date-picker"
+        {granularity}
+        value={normalizedValue.start}
         max={normalizedValue.end ?? undefined}
-        step={inputStep}
         {disabled}
-        aria-invalid={invalid}
+        aria-invalid={hasError ? 'true' : undefined}
         aria-describedby={describedBy}
-        onchange={handleStartChange}
+        onchange={(next) => handleStartChange(next)}
       />
     </div>
 
@@ -389,17 +373,16 @@
       >
         {resolvedEndLabel}
       </label>
-      <input
+      <DatePicker
         id={endId}
-        type={inputType}
-        class="cinder-date-range-field__date-input"
-        value={normalizedValue.end ?? ''}
+        class="cinder-date-range-field__date-picker"
+        {granularity}
+        value={normalizedValue.end}
         min={normalizedValue.start ?? undefined}
-        step={inputStep}
         {disabled}
-        aria-invalid={invalid}
+        aria-invalid={hasError ? 'true' : undefined}
         aria-describedby={describedBy}
-        onchange={handleEndChange}
+        onchange={(next) => handleEndChange(next)}
       />
     </div>
   </div>

package/src/components/description-list/description-list.examples.json

@@ -9,6 +9,12 @@
       "description": "Key–value metadata pairs in the default stacked layout.",
       "code": "<script lang=\"ts\">\n  import { DescriptionList } from '@lostgradient/cinder/description-list';\n  import type { DescriptionListItem } from '@lostgradient/cinder/description-list';\n\n  const items: DescriptionListItem[] = [\n    { term: 'Component', definition: 'DescriptionList' },\n    { term: 'Status', definition: 'Stable' },\n    { term: 'Version', definition: '1.0.0' },\n    { term: 'License', definition: 'MIT' },\n    { term: 'Maintainer', definition: 'Cinder team' },\n  ];\n</script>\n\n<DescriptionList {items} />\n"
     },
+    {
+      "id": "rich-definitions",
+      "title": "Description list rich definitions",
+      "description": "Definitions can render rich snippet content when plain text is not enough.",
+      "code": "<script lang=\"ts\">\n  import { DescriptionList } from '@lostgradient/cinder/description-list';\n  import type { DescriptionListItem } from '@lostgradient/cinder/description-list';\n\n  const items: DescriptionListItem[] = [\n    { term: 'Run ID', definition: runIdDefinition },\n    { term: 'Status', definition: statusDefinition },\n  ];\n</script>\n\n{#snippet runIdDefinition()}\n  <code>abc-123</code>\n{/snippet}\n\n{#snippet statusDefinition()}\n  <span class=\"example-status\">Active</span>\n{/snippet}\n\n<DescriptionList {items} />\n"
+    },
     {
       "id": "variants",
       "title": "Description list variants",

package/src/components/description-list/description-list.svelte

@@ -73,7 +73,13 @@
     <div class="cinder-description-list__row">
       <dt class={variant === 'narrow' ? 'cinder-sr-only' : undefined}>{item.term}</dt>
       <dd>
-        <div class="cinder-description-list__definition">{item.definition}</div>
+        <div class="cinder-description-list__definition">
+          {#if typeof item.definition === 'string'}
+            {item.definition}
+          {:else}
+            {@render item.definition()}
+          {/if}
+        </div>
         {#if actions}
           <div class="cinder-description-list__actions">{@render actions(item)}</div>
         {/if}

package/src/components/description-list/description-list.types.ts

@@ -2,6 +2,8 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 /** Layout variant for the description list. */
 export type DescriptionListVariant = 'default' | 'striped' | 'two-column' | 'narrow';
+/** Term definition content: plain text or rich snippet content. */
+export type DescriptionListDefinition = string | Snippet;
 export type DescriptionListItem = {
   /**
    * Stable identity for keyed rendering. Falls back to `term` when omitted.
@@ -10,8 +12,8 @@ export type DescriptionListItem = {
   id?: string;
   /** The label rendered inside `<dt>`. */
   term: string;
-  /** The value rendered inside `<dd>`. */
-  definition: string;
+  /** The value rendered inside `<dd>`. May be plain text or a snippet. */
+  definition: DescriptionListDefinition;
 };
 export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'class'> & {
   items: DescriptionListItem[];

package/src/components/description-list/index.ts

@@ -3,6 +3,7 @@ import DescriptionList from './description-list.svelte';
 
 export default DescriptionList;
 export type {
+  DescriptionListDefinition,
   DescriptionListItem,
   DescriptionListProps,
   DescriptionListVariant,