@shabboo/kit 0.0.0-stage → 0.1.1

package/src/ui/Disclosure.astro

@@ -0,0 +1,197 @@
+---
+/**
+ * An expandable section on a native <details>: no JS, keyboard and find-in-page for free.
+ * `summary` prop or slot "summary"; `name` makes a group where only one is open (an accordion).
+ */
+import type { HTMLAttributes } from "astro/types";
+import Icon from "./Icon.astro";
+
+interface Props extends HTMLAttributes<"details"> {
+  summary?: string;
+  size?: "sm" | "md";
+  /** boxed: a bordered panel instead of a bare line */
+  boxed?: boolean;
+}
+
+const { summary, size = "md", boxed = false, class: className, ...rest } = Astro.props;
+---
+
+<details class:list={["disclosure", className, { boxed }]} data-size={size} {...rest}>
+  <summary>
+    <Icon name="chevron-right" size="sm" class="chev" />
+    <span><slot name="summary">{summary}</slot></span>
+  </summary>
+  <div class="disclosure-body"><slot /></div>
+</details>
+
+<script>
+  // flags a disclosure the reader just opened, so its glide and dither never run on page load or a page swap;
+  // a click on <summary> lands before the toggle, so the first style that sees [open] sees this too
+  document.addEventListener("click", (event) => {
+    const details = (event.target as Element | null)?.closest?.("details.disclosure > summary")?.parentElement;
+    if (!(details instanceof HTMLDetailsElement)) return;
+    details.dataset.opening = "";
+    setTimeout(() => delete details.dataset.opening, 600);
+  });
+</script>
+
+<style>
+  .disclosure {
+    border-block-end: 1px dashed var(--stroke);
+  }
+  .boxed {
+    border: 1px solid var(--stroke);
+    border-radius: var(--radius);
+    background: var(--surface-raised);
+  }
+  summary {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding-block: var(--space-3);
+    cursor: pointer;
+    list-style: none;
+  }
+  summary::-webkit-details-marker {
+    display: none;
+  }
+  .boxed summary {
+    padding-inline: var(--space-4);
+  }
+  .disclosure[data-size="sm"] summary {
+    padding-block: var(--space-2);
+    font-size: var(--step--1);
+  }
+  summary:hover {
+    background: var(--state-hover);
+    color: var(--text-accent);
+  }
+  summary:active {
+    background: var(--state-active);
+  }
+  /* on touch, a small summary grows to --target-min itself: stacked rows sit too close to grow only the hit area */
+  @media (pointer: coarse) {
+    .disclosure[data-size="sm"] summary {
+      min-block-size: var(--target-min);
+    }
+  }
+  summary :global(.chev) {
+    color: var(--text-accent);
+  }
+  /* the chevron points down when open; in RTL it is already mirrored, so it turns the other way */
+  .disclosure[open] > summary :global(.chev) {
+    rotate: 90deg;
+  }
+  .disclosure[open] > summary:dir(rtl) :global(.chev) {
+    rotate: -90deg;
+  }
+  /*
+   * Open and close: the height glides, and each line of the body prints in on its own frame while it
+   * dithers to solid through 8-bit patterns (25% → 50% → 75% → 100%); closing runs bottom-up.
+   * Lines are the body's children, or the whole body when it holds bare text. The height needs
+   * interpolate-size and ::details-content; without them it snaps and only the dither runs.
+   * Opening plays only while data-opening is set (the reader's click); one rendered open just shows.
+   * At rest the mask is off: a mask clips to the border box and would cut off focus rings and shadows.
+   */
+  @media (prefers-reduced-motion: no-preference) {
+    summary :global(.chev) {
+      transition: rotate calc(var(--dur-step) * 0.6) steps(2, end);
+    }
+    .disclosure {
+      interpolate-size: allow-keywords;
+    }
+    .disclosure::details-content {
+      block-size: 0;
+      overflow: clip;
+      transition:
+        block-size calc(var(--dur-step) * 1.5) var(--ease),
+        content-visibility calc(var(--dur-step) * 1.5) allow-discrete;
+    }
+    .disclosure[open]::details-content {
+      block-size: auto;
+    }
+    @starting-style {
+      .disclosure[open][data-opening]::details-content {
+        block-size: 0;
+      }
+    }
+    .disclosure-body > :global(*),
+    .disclosure-body:not(:has(> *)) {
+      --dither: 0;
+      mask-image:
+        conic-gradient(black 25%, transparent 0),
+        conic-gradient(transparent 50%, black 0 75%, transparent 0),
+        conic-gradient(transparent 75%, black 0),
+        conic-gradient(transparent 25%, black 0 50%, transparent 0);
+      mask-size:
+        calc(4px * clamp(0, var(--dither), 1)) calc(4px * clamp(0, var(--dither), 1)),
+        calc(4px * clamp(0, var(--dither) - 1, 1)) calc(4px * clamp(0, var(--dither) - 1, 1)),
+        calc(4px * clamp(0, var(--dither) - 2, 1)) calc(4px * clamp(0, var(--dither) - 2, 1)),
+        calc(4px * clamp(0, var(--dither) - 3, 1)) calc(4px * clamp(0, var(--dither) - 3, 1));
+      mask-repeat: repeat;
+      transition: --dither var(--dur-fast) var(--ease-dither);
+    }
+    [open] > .disclosure-body > :global(*),
+    [open] > .disclosure-body:not(:has(> *)) {
+      --dither: 4;
+    }
+    [open]:not([data-opening]) > .disclosure-body > :global(*),
+    [open]:not([data-opening]) > .disclosure-body:not(:has(> *)) {
+      mask-image: none;
+    }
+    /* hidden content gets no style updates, so opening animates in rather than transitions */
+    [open][data-opening] > .disclosure-body > :global(*),
+    [open][data-opening] > .disclosure-body:not(:has(> *)) {
+      animation: disclosure-dither var(--dur-fast) var(--ease-dither) backwards;
+    }
+    [open][data-opening] > .disclosure-body > :global(:nth-child(2)) {
+      animation-delay: 30ms;
+    }
+    [open][data-opening] > .disclosure-body > :global(:nth-child(3)) {
+      animation-delay: 60ms;
+    }
+    [open][data-opening] > .disclosure-body > :global(:nth-child(4)) {
+      animation-delay: 90ms;
+    }
+    [open][data-opening] > .disclosure-body > :global(:nth-child(n + 5)) {
+      animation-delay: 120ms;
+    }
+    :not([open]) > .disclosure-body > :global(:nth-last-child(2)) {
+      transition-delay: 30ms;
+    }
+    :not([open]) > .disclosure-body > :global(:nth-last-child(3)) {
+      transition-delay: 60ms;
+    }
+    :not([open]) > .disclosure-body > :global(:nth-last-child(4)) {
+      transition-delay: 90ms;
+    }
+    :not([open]) > .disclosure-body > :global(:nth-last-child(n + 5)) {
+      transition-delay: 120ms;
+    }
+  }
+  @keyframes disclosure-dither {
+    from {
+      --dither: 0;
+    }
+    to {
+      --dither: 4;
+    }
+  }
+  .disclosure-body {
+    padding-block: 0 var(--space-4);
+    padding-inline-start: calc(1em + var(--space-2));
+    color: var(--text-muted);
+  }
+  .boxed .disclosure-body {
+    padding-inline: var(--space-4);
+  }
+</style>
+
+<style is:global>
+  /* the dither step (0–4) must be a registered integer so it can transition and animate */
+  @property --dither {
+    syntax: "<integer>";
+    inherits: false;
+    initial-value: 4;
+  }
+</style>

package/src/ui/EntryItem.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * One dated entry in a list (a post, a note): an h-entry with its date label, title link and summary.
+ * The caller formats the date for its locale. default slot: extras below the summary (tags).
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"article"> {
+  href: string;
+  title: string;
+  /** machine-readable date, e.g. an ISO string */
+  datetime: string;
+  /** the date as shown, already localized */
+  date: string;
+  summary?: string;
+  headingLevel?: 2 | 3 | 4;
+}
+
+const { href, title, datetime, date, summary, headingLevel = 3, class: className, ...rest } = Astro.props;
+const H = `h${headingLevel}` as "h2" | "h3" | "h4";
+---
+
+<article class:list={["entry h-entry", className]} {...rest}>
+  <p class="label">
+    <time class="dt-published" datetime={datetime}>{date}</time>
+  </p>
+  <H class="entry-title"><a class="p-name u-url" href={href}>{title}</a></H>
+  {summary && <p class="p-summary">{summary}</p>}
+  <slot />
+</article>
+
+<style>
+  .entry-title {
+    font-size: var(--step-2);
+    margin-block: var(--space-1) var(--space-2);
+  }
+  .entry-title a {
+    text-decoration: none;
+  }
+  .p-summary {
+    color: var(--text-muted);
+  }
+</style>

package/src/ui/Field.astro

@@ -0,0 +1,167 @@
+---
+/**
+ * A form control with its label, hint and error, wired with aria-describedby / aria-invalid.
+ * control: input (default) · textarea · select (options in the default slot).
+ * Extra attributes (name, type, required, placeholder…) go to the control.
+ */
+import type { HTMLAttributes } from "astro/types";
+import Icon from "./Icon.astro";
+
+type Control = HTMLAttributes<"input"> & HTMLAttributes<"textarea"> & HTMLAttributes<"select">;
+
+interface Props extends Omit<Control, "id"> {
+  id: string;
+  label: string;
+  hint?: string;
+  error?: string;
+  control?: "input" | "textarea" | "select";
+  size?: "sm" | "md" | "lg";
+}
+
+const {
+  id,
+  label,
+  hint,
+  error,
+  control = "input",
+  size = "md",
+  class: className,
+  "aria-describedby": extraDescribedBy,
+  ...props
+} = Astro.props;
+const Tag = control;
+/* the scope attribute a styled parent passes along belongs on the root, with `class`, not on the control */
+const isScope = (key: string) => key.startsWith("data-astro-cid-");
+const scope = Object.fromEntries(Object.entries(props).filter(([key]) => isScope(key)));
+const rest = Object.fromEntries(Object.entries(props).filter(([key]) => !isScope(key))) as typeof props;
+/* the caller's own descriptions are kept, after the hint and the error */
+const describedBy =
+  [hint && `${id}-hint`, error && `${id}-error`, extraDescribedBy].filter(Boolean).join(" ") || undefined;
+---
+
+<div class:list={["field", className]} data-size={size} {...scope}>
+  <label for={id}>{label}{rest.required && <span class="req" aria-hidden="true"> *</span>}</label>
+  <Tag
+    id={id}
+    class="control"
+    aria-describedby={describedBy}
+    aria-invalid={error ? "true" : undefined}
+    {...rest}
+  ><slot /></Tag>
+  {hint && <p class="hint" id={`${id}-hint`}>{hint}</p>}
+  {error && <p class="error" id={`${id}-error`}><Icon name="warning" size="sm" />{error}</p>}
+</div>
+
+<style>
+  .field {
+    display: grid;
+    gap: var(--space-1);
+    min-inline-size: 0;
+  }
+  label {
+    font-family: var(--font-mono);
+    font-size: var(--step--2);
+    letter-spacing: var(--tracking-mono);
+    text-transform: uppercase;
+    color: var(--text-muted);
+  }
+  .field:is(:lang(fa), :lang(ar)) label {
+    font-family: var(--font-arabic);
+    font-size: var(--step--1);
+    letter-spacing: 0;
+  }
+  .req {
+    color: var(--text-signal);
+  }
+  .control {
+    inline-size: 100%;
+    min-block-size: var(--control-h-md);
+    padding-inline: var(--control-pad-md);
+    border: 1px solid var(--stroke-control);
+    border-radius: var(--radius);
+    background: var(--field);
+    color: var(--text);
+    font-size: var(--step--1);
+    caret-color: var(--text-accent);
+    caret-shape: block;
+    transition: border-color var(--dur-step) var(--ease-step);
+  }
+  textarea.control {
+    padding-block: var(--space-2);
+    min-block-size: 6rem;
+    resize: vertical;
+    line-height: var(--leading);
+  }
+  .control::placeholder {
+    color: var(--text-placeholder);
+  }
+  .control:hover {
+    border-color: var(--text-muted);
+    background: linear-gradient(var(--state-hover), var(--state-hover)), var(--field);
+  }
+  .control:disabled {
+    border-color: var(--stroke-subtle);
+    background: var(--fill-disabled);
+    color: var(--text-disabled);
+    cursor: not-allowed;
+  }
+  /* [readonly], not :read-only: that also matches checkbox, range, color and file, which can't be read-only */
+  .control[readonly]:not(select, :disabled) {
+    border-style: dashed;
+    background: none;
+  }
+  .control:focus-visible {
+    border-color: var(--stroke-strong);
+    outline-offset: 1px;
+  }
+  .field[data-size="sm"] .control {
+    min-block-size: var(--control-h-sm);
+    padding-inline: var(--control-pad-sm);
+    font-size: var(--step--2);
+  }
+  .field[data-size="lg"] .control {
+    min-block-size: var(--control-h-lg);
+    padding-inline: var(--control-pad-lg);
+    font-size: var(--step-0);
+  }
+  /* on touch, a field grows to --target-min itself: a native control has no pseudo-element to carry a hit area */
+  @media (pointer: coarse) {
+    .field[data-size] .control:not(textarea) {
+      min-block-size: var(--target-min);
+    }
+  }
+  .control[aria-invalid="true"] {
+    border-color: var(--status-error);
+  }
+  /* a wrong value judders once when the field is focused */
+  @media (prefers-reduced-motion: no-preference) {
+    .control[aria-invalid="true"]:focus-visible {
+      animation: field-judder calc(var(--dur-step) * 1.5) steps(1, end);
+    }
+  }
+  @keyframes field-judder {
+    0% {
+      translate: -3px 0;
+    }
+    33% {
+      translate: 3px 0;
+    }
+    66% {
+      translate: -1px 0;
+    }
+    100% {
+      translate: 0 0;
+    }
+  }
+  .hint {
+    font-size: var(--step--1);
+    color: var(--text-helper);
+  }
+  .error {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-2);
+    font-size: var(--step--1);
+    color: var(--status-error);
+  }
+</style>

package/src/ui/Figure.astro

@@ -0,0 +1,47 @@
+---
+/**
+ * Media with a caption. The media goes in the default slot (an <img>, astro:assets <Image>, <video>…);
+ * the caption is the `caption` prop or slot "caption".
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"figure"> {
+  caption?: string;
+  /** frame: a thin border around the media */
+  framed?: boolean;
+}
+
+const { caption, framed = false, class: className, ...rest } = Astro.props;
+const hasCaption = Boolean(caption) || Astro.slots.has("caption");
+---
+
+<figure class:list={["figure", className, { framed }]} {...rest}>
+  <div class="figure-media"><slot /></div>
+  {
+    hasCaption && (
+      <figcaption class="label">
+        <slot name="caption">{caption}</slot>
+      </figcaption>
+    )
+  }
+</figure>
+
+<style>
+  .figure {
+    display: grid;
+    gap: var(--space-2);
+  }
+  .figure-media > :global(*) {
+    inline-size: 100%;
+    border-radius: var(--radius);
+  }
+  .framed .figure-media {
+    padding: var(--space-2);
+    border: 1px solid var(--stroke);
+    border-radius: var(--radius);
+    background: var(--surface-raised);
+  }
+  figcaption {
+    text-transform: none;
+  }
+</style>

package/src/ui/HCard.astro

@@ -0,0 +1,86 @@
+---
+/** A person card (microformats h-card): photo, name, a line about them and their links. */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  name: string;
+  url?: string;
+  photo?: string;
+  /** a short line under the name (p-note) */
+  note?: string;
+  links?: { label: string; href: string }[];
+  size?: "sm" | "md";
+}
+
+const { name, url, photo, note, links = [], size = "md", class: className, ...rest } = Astro.props;
+---
+
+<div class:list={["hcard h-card", className]} data-size={size} {...rest}>
+  {photo && <img class="u-photo" src={photo} alt="" width="64" height="64" loading="lazy" decoding="async" />}
+  <div class="hcard-text">
+    {url ? <a class="p-name u-url" href={url} rel="me">{name}</a> : <span class="p-name">{name}</span>}
+    {note && <p class="p-note">{note}</p>}
+    {
+      links.length > 0 && (
+        <ul class="hcard-links label">
+          {links.map((l) => (
+            <li>
+              <a class="u-url" href={l.href} rel="me">
+                {l.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      )
+    }
+  </div>
+</div>
+
+<style>
+  .hcard {
+    display: flex;
+    align-items: center;
+    gap: var(--space-4);
+  }
+  .u-photo {
+    inline-size: 4rem;
+    block-size: 4rem;
+    border-radius: 50%;
+    border: 1px solid var(--stroke);
+    object-fit: cover;
+  }
+  .hcard[data-size="sm"] .u-photo {
+    inline-size: 2.5rem;
+    block-size: 2.5rem;
+  }
+  .hcard-text {
+    display: grid;
+    gap: var(--space-1);
+  }
+  .p-name {
+    font-size: var(--step-1);
+    text-decoration: none;
+  }
+  .hcard[data-size="sm"] .p-name {
+    font-size: var(--step-0);
+  }
+  .p-note {
+    color: var(--text-muted);
+    font-style: italic;
+  }
+  .hcard-links {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-3);
+    list-style: none;
+    padding: 0;
+  }
+  .hcard-links a {
+    text-decoration: none;
+  }
+  /* Persian and Arabic script is never slanted */
+  :is(:lang(fa), :lang(ar)) :where(*),
+  :is(:lang(fa), :lang(ar)) {
+    font-style: normal;
+  }
+</style>

package/src/ui/Icon.astro

@@ -0,0 +1,59 @@
+---
+/**
+ * A small inline SVG icon set, drawn on a 24px grid with a 1.5 stroke in currentColor.
+ * Decorative by default (aria-hidden); pass `label` when the icon is the only content.
+ * Directional icons (arrows, chevrons) mirror in RTL.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+import { type IconName, PATHS } from "./icons";
+
+const MIRRORED: IconName[] = ["arrow-right", "arrow-left", "chevron-right"];
+
+interface Props extends HTMLAttributes<"svg"> {
+  name: IconName;
+  size?: "sm" | "md" | "lg";
+  /** accessible name; without it the icon is hidden from assistive tech */
+  label?: string;
+}
+
+const { name, size = "md", label, class: className, ...rest } = Astro.props;
+---
+
+<svg
+  class:list={["icon", className, { mirror: MIRRORED.includes(name) }]}
+  data-size={size}
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.5"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  role={label ? "img" : undefined}
+  aria-label={label}
+  aria-hidden={label ? undefined : "true"}
+  focusable="false"
+  {...rest}><path d={PATHS[name]}></path></svg
+>
+
+<style>
+  .icon {
+    display: inline-block;
+    flex: none;
+    inline-size: var(--icon-md);
+    block-size: var(--icon-md);
+    vertical-align: -0.2em;
+  }
+  .icon[data-size="sm"] {
+    inline-size: var(--icon-sm);
+    block-size: var(--icon-sm);
+    vertical-align: -0.125em;
+  }
+  .icon[data-size="lg"] {
+    inline-size: var(--icon-lg);
+    block-size: var(--icon-lg);
+  }
+  .mirror:dir(rtl) {
+    transform: scaleX(-1);
+  }
+</style>

package/src/ui/Kbd.astro

@@ -0,0 +1,35 @@
+---
+/** A keyboard key, e.g. <Kbd>Esc</Kbd>. */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"kbd"> {
+  size?: "sm" | "md";
+}
+
+const { size = "md", class: className, ...rest } = Astro.props;
+---
+
+<kbd class:list={["kbd", className]} data-size={size} {...rest}><slot /></kbd>
+
+<style>
+  .kbd {
+    display: inline-block;
+    min-inline-size: 1.6em;
+    padding: 0.05em 0.4em;
+    border: 1px solid var(--stroke);
+    border-block-end-width: 2px;
+    border-radius: var(--radius);
+    background: var(--surface-sunken);
+    color: var(--text);
+    font-family: var(--font-mono);
+    font-size: 0.8em;
+    line-height: 1.5;
+    text-align: center;
+  }
+  .kbd:is(:lang(fa), :lang(ar)) {
+    font-family: var(--font-arabic);
+  }
+  .kbd[data-size="sm"] {
+    font-size: 0.7em;
+  }
+</style>

package/src/ui/Label.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * The mono uppercase metadata label used everywhere. It applies the global `.label` utility,
+ * so the fa/ar override in global.css (Arabic face, no letter-spacing) keeps working.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"p"> {
+  as?: "p" | "span" | "div" | "h2" | "h3" | "h4";
+}
+
+const { as: Tag = "p", class: className, ...rest } = Astro.props;
+---
+
+<Tag class:list={["label", className]} {...rest}><slot /></Tag>