@lostgradient/cinder 0.4.0 → 0.5.0

package/src/components/blog-section/blog-section.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "blog-section",
+  "import": "@lostgradient/cinder/blog-section",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "BlogSection",
+      "description": "BlogSection showing recent articles with category, excerpt, and author attribution.",
+      "code": "<script lang=\"ts\">\n  import { BlogSection } from '@lostgradient/cinder/blog-section';\n\n  const posts = [\n    {\n      title: 'How we scaled our design system governance',\n      excerpt: 'A practical playbook for cross-team contributions and review workflows.',\n      href: '#',\n      category: 'Engineering',\n      publishedAt: 'Jun 20, 2026',\n      authorName: 'Morgan Yu',\n      authorRole: 'Staff Engineer',\n      imageSrc: 'https://placehold.co/640x360?text=Design+System',\n    },\n    {\n      title: 'Product launch checklist for frontend teams',\n      excerpt: 'A repeatable checklist that reduces launch-day surprises.',\n      href: '#',\n      category: 'Product',\n      publishedAt: 'Jun 8, 2026',\n      authorName: 'Jamie Patel',\n      authorRole: 'Product Manager',\n      imageSrc: 'https://placehold.co/640x360?text=Launch+Checklist',\n    },\n    {\n      title: 'Accessibility debt: how to find and fix it early',\n      excerpt: 'Methods for integrating inclusive QA before code reaches production.',\n      href: '#',\n      category: 'Accessibility',\n      publishedAt: 'May 27, 2026',\n      authorName: 'Casey Murray',\n      authorRole: 'Design Systems Lead',\n      imageSrc: 'https://placehold.co/640x360?text=A11y+Debt',\n    },\n  ];\n</script>\n\n<BlogSection\n  title=\"Latest from the Cinder blog\"\n  description=\"Guides, launch lessons, and design-system practices from our product team.\"\n  {posts}\n/>\n"
+    }
+  ]
+}

package/src/components/blog-section/blog-section.svelte

@@ -0,0 +1,107 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category domain
+   * @status stable
+   * @purpose Blog/article listing section that renders post cards with metadata, excerpt text, and author attribution.
+   * @tag marketing
+   * @tag blog
+   * @tag content
+   * @useWhen Showing recent posts or resources on a landing page.
+   * @useWhen Building a featured-articles grid with author and publish metadata.
+   * @avoidWhen Rendering partner logos or brand marks only. | logo-cloud
+   * @avoidWhen Presenting customer testimonials in quote format. | testimonial-section
+   * @related logo-cloud, testimonial-section, card, avatar, container
+   */
+  export type { BlogSectionPost, BlogSectionProps } from './blog-section.types.ts';
+</script>
+
+<script lang="ts">
+  import Avatar from '../avatar/avatar.svelte';
+  import Container from '../container/container.svelte';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  import type { BlogSectionProps } from './blog-section.types.ts';
+
+  let {
+    as = 'section',
+    title,
+    description,
+    posts,
+    columns = 3,
+    maxWidth = 'wide',
+    class: className,
+    ...rest
+  }: BlogSectionProps = $props();
+
+  function avatarProps(name: string, src: string | undefined): { name: string; src?: string } {
+    return src ? { name, src } : { name };
+  }
+
+  function postMetadata(category: string | undefined, publishedAt: string | undefined): string {
+    return [category, publishedAt].filter(Boolean).join(' · ');
+  }
+</script>
+
+<svelte:element
+  this={as}
+  class={classNames('cinder-blog-section', className)}
+  data-cinder-columns={String(columns)}
+  {...rest}
+>
+  <Container {maxWidth}>
+    <div class="cinder-blog-section__inner">
+      {#if title || description}
+        <header class="cinder-blog-section__header">
+          {#if title}
+            <h2 class="cinder-blog-section__title">{title}</h2>
+          {/if}
+          {#if description}
+            <p class="cinder-blog-section__description">{description}</p>
+          {/if}
+        </header>
+      {/if}
+
+      <ul class="cinder-blog-section__list">
+        {#each posts as post, index (`${post.title}-${index}`)}
+          <li class="cinder-blog-section__item">
+            <article class="cinder-card" data-cinder-variant="card">
+              <div
+                class="cinder-card__body"
+                data-cinder-tone="default"
+                data-cinder-padding="default"
+              >
+                {#if post.imageSrc}
+                  <img
+                    class="cinder-blog-section__image"
+                    src={post.imageSrc}
+                    alt=""
+                    loading="lazy"
+                  />
+                {/if}
+                {#if post.category || post.publishedAt}
+                  <p class="cinder-blog-section__meta">
+                    {postMetadata(post.category, post.publishedAt)}
+                  </p>
+                {/if}
+                <h3 class="cinder-blog-section__post-title">
+                  <a href={post.href} class="cinder-blog-section__link">{post.title}</a>
+                </h3>
+                <p class="cinder-blog-section__excerpt">{post.excerpt}</p>
+                <div class="cinder-blog-section__author">
+                  <Avatar {...avatarProps(post.authorName, post.authorAvatarSrc)} size="sm" />
+                  <div class="cinder-blog-section__author-meta">
+                    <p class="cinder-blog-section__author-name">{post.authorName}</p>
+                    {#if post.authorRole}
+                      <p class="cinder-blog-section__author-role">{post.authorRole}</p>
+                    {/if}
+                  </div>
+                </div>
+              </div>
+            </article>
+          </li>
+        {/each}
+      </ul>
+    </div>
+  </Container>
+</svelte:element>

package/src/components/blog-section/blog-section.types.ts

@@ -0,0 +1,59 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ContainerMaxWidth } from '../container/container.types.ts';
+
+/** @schemaObject */
+export type BlogSectionPost = {
+  /** Post title text. */
+  title: string;
+  /** Summary/excerpt text. */
+  excerpt: string;
+  /** URL to the full article. */
+  href: string;
+  /** Optional category label. */
+  category?: string;
+  /** Optional thumbnail image source. */
+  imageSrc?: string;
+  /** Optional publish date string. */
+  publishedAt?: string;
+  /** Author display name. */
+  authorName: string;
+  /** Optional author role/title text. */
+  authorRole?: string;
+  /** Optional author avatar image source. */
+  authorAvatarSrc?: string;
+};
+
+/** Props for the BlogSection component. */
+export type BlogSectionProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> & {
+  /** Wrapper element tag. @default "section" */
+  as?: 'section' | 'div';
+  /** Optional section heading text. */
+  title?: string;
+  /** Optional section description text. */
+  description?: string;
+  /** Posts to render in the section. */
+  posts: BlogSectionPost[];
+  /** Grid column count. @default 3 */
+  columns?: 1 | 2 | 3;
+  /** Max width token forwarded to Container. @default "wide" */
+  maxWidth?: ContainerMaxWidth;
+  /** Custom class merged with `.cinder-blog-section`. */
+  class?: string;
+};
+
+export interface BlogSectionSchemaProps {
+  /** Wrapper element tag. @default "section" */
+  as?: 'section' | 'div';
+  /** Optional section heading text. */
+  title?: string;
+  /** Optional section description text. */
+  description?: string;
+  /** Posts to render in the section. */
+  posts: BlogSectionPost[];
+  /** Grid column count. @default 3 */
+  columns?: 1 | 2 | 3;
+  /** Max width token forwarded to Container. @default "wide" */
+  maxWidth?: ContainerMaxWidth;
+  /** Custom class merged with `.cinder-blog-section`. */
+  class?: string;
+}

package/src/components/blog-section/index.ts

@@ -0,0 +1,6 @@
+import './blog-section.css';
+import BlogSection from './blog-section.svelte';
+
+export default BlogSection;
+export type { BlogSectionPost, BlogSectionProps } from './blog-section.types.ts';
+export { BlogSection };

package/src/components/calendar/calendar.css

@@ -0,0 +1,105 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@layer cinder.components {
+  .cinder-calendar {
+    display: grid;
+    gap: var(--cinder-space-2);
+    inline-size: min(20rem, 100%);
+  }
+
+  .cinder-calendar__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+  }
+
+  .cinder-calendar__nav {
+    appearance: none;
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-sm);
+    background: var(--cinder-surface-raised);
+    color: var(--cinder-text);
+    inline-size: 2rem;
+    block-size: 2rem;
+    cursor: pointer;
+  }
+
+  .cinder-calendar__nav:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .cinder-calendar__title {
+    margin: 0;
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text);
+  }
+
+  .cinder-calendar__weekdays,
+  .cinder-calendar__grid-row {
+    display: grid;
+    grid-template-columns: repeat(7, minmax(0, 1fr));
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-calendar__weekday {
+    font-size: var(--cinder-text-xs);
+    text-align: center;
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-calendar__grid {
+    display: grid;
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-calendar__gridcell {
+    display: grid;
+  }
+
+  .cinder-calendar__day {
+    appearance: none;
+    border: 1px solid transparent;
+    border-radius: var(--cinder-radius-sm);
+    background: transparent;
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-sm);
+    inline-size: 100%;
+    block-size: 2rem;
+    cursor: pointer;
+  }
+
+  .cinder-calendar__day[data-outside] {
+    color: var(--cinder-text-subtle);
+  }
+
+  .cinder-calendar__day[data-selected] {
+    background: color-mix(in oklch, var(--cinder-accent), transparent 84%);
+    border-color: var(--cinder-accent);
+    color: var(--cinder-accent-text);
+  }
+
+  .cinder-calendar__day[data-focused] {
+    box-shadow: inset 0 0 0 1px var(--cinder-ring-color);
+  }
+
+  .cinder-calendar__day[aria-disabled='true'] {
+    color: var(--cinder-text-disabled);
+    cursor: not-allowed;
+  }
+
+  .cinder-calendar__day:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-calendar__day:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 1px;
+      box-shadow: none;
+    }
+  }
+}

package/src/components/calendar/calendar.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "calendar",
+  "import": "@lostgradient/cinder/calendar",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic calendar",
+      "description": "Keyboard-navigable calendar grid with controlled ISO date value.",
+      "code": "<script lang=\"ts\">\n  import { Calendar } from '@lostgradient/cinder/calendar';\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  <Calendar bind:value />\n  <code>{value ?? 'undefined'}</code>\n</div>\n"
+    }
+  ]
+}

package/src/components/calendar/calendar.svelte

@@ -0,0 +1,373 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status alpha
+   * @purpose Keyboard-navigable month grid for choosing a calendar date with full styling control and min/max constraints.
+   * @tag form
+   * @tag date
+   * @tag calendar
+   * @useWhen Rendering a custom date-grid picker inside an input popover.
+   * @useWhen Requiring consistent cross-browser calendar behavior that native date controls cannot provide.
+   * @avoidWhen A plain browser-managed date input is sufficient and custom keyboard semantics are not required.
+   * @related date-picker, date-range-field
+   */
+  export type { CalendarProps } from './calendar.types.ts';
+</script>
+
+<script lang="ts">
+  import { tick, untrack } from 'svelte';
+  import type { CalendarProps } from './calendar.types.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  type CalendarCell = {
+    iso: string;
+    day: number;
+    inMonth: boolean;
+    disabled: boolean;
+    focused: boolean;
+    selected: boolean;
+    ariaLabel: string;
+  };
+
+  const WEEKDAY_INDEXES = [0, 1, 2, 3, 4, 5, 6] as const;
+
+  let {
+    id,
+    value = $bindable<string | undefined>(undefined),
+    month,
+    min,
+    max,
+    firstDayOfWeek = 0,
+    locale = 'en-US',
+    label = 'Calendar',
+    disabled = false,
+    class: className,
+    onchange,
+    disabledDate,
+    ...rest
+  }: CalendarProps = $props();
+
+  const generatedId = $props.id();
+  const rootId = $derived(id ?? generatedId);
+  const titleId = $derived(`${rootId}-title`);
+  const monthGridId = $derived(`${rootId}-grid`);
+
+  function parseISODate(iso: string | undefined): Date | null {
+    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: Date): string {
+    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: Date): Date {
+    return new Date(date.getFullYear(), date.getMonth(), 1);
+  }
+
+  function addDays(date: Date, days: number): Date {
+    const next = new Date(date);
+    next.setDate(next.getDate() + days);
+    return next;
+  }
+
+  function addMonths(date: Date, months: number): Date {
+    return new Date(date.getFullYear(), date.getMonth() + months, 1);
+  }
+
+  function startOfWeek(date: Date, weekStart: number): Date {
+    const offset = (date.getDay() - weekStart + 7) % 7;
+    return addDays(date, -offset);
+  }
+
+  function isISOWithinBounds(iso: string): boolean {
+    if (min && iso < min) return false;
+    if (max && iso > max) return false;
+    return true;
+  }
+
+  function isDateDisabled(iso: string): boolean {
+    if (!isISOWithinBounds(iso)) return true;
+    return disabledDate?.(iso) ?? false;
+  }
+
+  function resolveAnchorIso(
+    valueProp: string | undefined,
+    monthProp: string | undefined,
+    fallbackIso: string,
+  ): string {
+    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<string | null>(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: CalendarCell[] = [];
+    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: CalendarCell[][] = [];
+    for (let index = 0; index < cells.length; index += 7) {
+      next.push(cells.slice(index, index + 7));
+    }
+    return next;
+  });
+
+  async function focusDate(iso: string, moveDomFocus = false) {
+    focusedIso = iso;
+    const parsed = parseISODate(iso);
+    if (parsed) {
+      visibleMonthDate = startOfMonth(parsed);
+    }
+    if (!moveDomFocus) return;
+    await tick();
+    const target = document.getElementById(focusedDayId) as HTMLButtonElement | null;
+    target?.focus();
+  }
+
+  function commitDate(iso: string) {
+    if (disabled || isDateDisabled(iso)) return;
+    value = iso;
+    focusedIso = iso;
+    onchange?.(iso);
+  }
+
+  async function moveFocusedByDays(delta: number) {
+    const base = parseISODate(focusedIso) ?? visibleMonthDate;
+    const next = addDays(base, delta);
+    await focusDate(toISODate(next), true);
+  }
+
+  function clampDayToMonth(year: number, monthValue: number, day: number): Date {
+    const lastDay = new Date(year, monthValue + 1, 0).getDate();
+    return new Date(year, monthValue, Math.min(day, lastDay));
+  }
+
+  async function moveFocusedByMonths(delta: number, 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: KeyboardEvent) {
+    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(): boolean {
+    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(): boolean {
+    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>