@shabboo/kit 0.0.0-stage → 0.1.0

package/src/ui/Pagination.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * Previous, numbered pages and next. Pass the pages you want shown (with `current` on one);
+ * a missing prev/next leaves an empty, hidden spacer in its place so the row doesn't jump.
+ */
+import type { HTMLAttributes } from "astro/types";
+import Icon from "./Icon.astro";
+
+interface PageLink {
+  href: string;
+  label: string;
+}
+
+interface Props extends HTMLAttributes<"nav"> {
+  prev?: PageLink;
+  next?: PageLink;
+  pages?: (PageLink & { current?: boolean })[];
+  /** accessible name of the nav landmark */
+  label?: string;
+}
+
+const { prev, next, pages = [], label = "Pagination", class: className, ...rest } = Astro.props;
+---
+
+<nav aria-label={label} class:list={["pager", className]} {...rest}>
+  {
+    prev ? (
+      <a class="end" href={prev.href} rel="prev">
+        <Icon name="arrow-left" size="sm" />
+        {prev.label}
+      </a>
+    ) : (
+      <span class="end off" aria-hidden="true" />
+    )
+  }
+  {
+    pages.length > 0 && (
+      <ol>
+        {pages.map((p) => (
+          <li>
+            <a href={p.href} aria-current={p.current ? "page" : undefined}>
+              {p.label}
+            </a>
+          </li>
+        ))}
+      </ol>
+    )
+  }
+  {
+    next ? (
+      <a class="end" href={next.href} rel="next">
+        {next.label}
+        <Icon name="arrow-right" size="sm" />
+      </a>
+    ) : (
+      <span class="end off" aria-hidden="true" />
+    )
+  }
+</nav>
+
+<style>
+  .pager {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-4);
+    font-family: var(--font-mono);
+    font-size: var(--step--1);
+  }
+  .pager:is(:lang(fa), :lang(ar)) {
+    font-family: var(--font-arabic);
+  }
+  a {
+    text-decoration: none;
+  }
+  .end {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2);
+    min-inline-size: 6rem;
+  }
+  .end:last-child {
+    justify-content: flex-end;
+  }
+  ol {
+    display: flex;
+    gap: var(--space-1);
+    list-style: none;
+    padding: 0;
+  }
+  ol a {
+    display: grid;
+    place-items: center;
+    min-inline-size: var(--control-h-sm);
+    min-block-size: var(--control-h-sm);
+    padding-inline: var(--space-1);
+    border: 1px solid transparent;
+    border-radius: var(--radius);
+    color: var(--text-muted);
+  }
+  ol a:hover {
+    border-color: var(--stroke);
+    background: var(--state-hover);
+  }
+  ol a:active {
+    background: var(--state-active);
+  }
+  ol a[aria-current="page"] {
+    border-color: var(--stroke-strong);
+    background: var(--state-selected);
+    color: var(--text-accent);
+  }
+  /* on touch, each page is a full --target-min square: the numbers sit too close to grow only the hit area */
+  @media (pointer: coarse) {
+    ol a {
+      min-inline-size: var(--target-min);
+      min-block-size: var(--target-min);
+    }
+    .end {
+      min-block-size: var(--target-min);
+    }
+  }
+</style>

package/src/ui/PixelFrame.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * The pixel style without sprites: a stepped border with notched corners, drawn with box-shadow
+ * steps around a panel (the HUD look). slot "title": a tab on the top edge, e.g. "ch 03".
+ * px: the size of one pixel step.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  tone?: "accent" | "muted" | "signal";
+  size?: "sm" | "md" | "lg";
+  title?: string;
+  /** CRT scanlines rolling over the panel */
+  scanlines?: boolean;
+}
+
+const { tone = "accent", size = "md", title, scanlines = false, class: className, ...rest } = Astro.props;
+const hasTitle = Boolean(title) || Astro.slots.has("title");
+---
+
+<div class:list={["pixel", className, { scanlines }]} data-tone={tone} data-size={size} {...rest}>
+  {
+    hasTitle && (
+      <p class="pixel-title">
+        <slot name="title">{title}</slot>
+      </p>
+    )
+  }
+  <slot />
+</div>
+
+<style>
+  .pixel {
+    --px: 4px;
+    --pixel-color: var(--fill-accent-strong);
+    /* the title tab: a fill and the text that reads on it at 4.5:1 or more, set together per tone */
+    --pixel-tab: var(--fill-accent);
+    --pixel-tab-text: var(--text-on-fill);
+    position: relative;
+    margin: var(--px);
+    padding: var(--space-4) var(--space-5);
+    background: var(--surface-raised);
+    /* four offset copies of the edge leave the corners notched: the classic 8-bit frame */
+    box-shadow:
+      0 calc(-1 * var(--px)) 0 0 var(--pixel-color),
+      0 var(--px) 0 0 var(--pixel-color),
+      calc(-1 * var(--px)) 0 0 0 var(--pixel-color),
+      var(--px) 0 0 0 var(--pixel-color),
+      0 calc(2 * var(--px)) 0 0 var(--surface-sunken);
+    image-rendering: pixelated;
+  }
+  .pixel[data-size="sm"] {
+    --px: 2px;
+    padding: var(--space-2) var(--space-3);
+    font-size: var(--step--1);
+  }
+  .pixel[data-size="lg"] {
+    --px: 6px;
+    padding: var(--space-5) var(--space-6);
+  }
+  .pixel[data-tone="muted"] {
+    --pixel-color: var(--stroke);
+    --pixel-tab: var(--stroke);
+    --pixel-tab-text: var(--text);
+  }
+  .pixel[data-tone="signal"] {
+    --pixel-color: var(--text-signal);
+    --pixel-tab: var(--text-signal);
+    --pixel-tab-text: var(--surface);
+  }
+  .pixel-title {
+    position: absolute;
+    inset-block-start: calc(-1 * var(--px) - 0.9em);
+    inset-inline-start: var(--space-4);
+    padding: 0.15em 0.6em;
+    background: var(--pixel-tab);
+    color: var(--pixel-tab-text);
+    font-family: var(--font-mono);
+    font-size: var(--step--2);
+    letter-spacing: var(--tracking-mono);
+    text-transform: uppercase;
+    line-height: 1.4;
+  }
+  .pixel-title:is(:lang(fa), :lang(ar)) {
+    font-family: var(--font-arabic);
+    letter-spacing: 0;
+  }
+  .scanlines::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    background: repeating-linear-gradient(to bottom, transparent 0 2px, var(--surface-sunken) 2px 3px);
+    opacity: 0.45;
+    mix-blend-mode: multiply;
+  }
+  /* both run under five seconds and then hold (WCAG 2.2.2); the roll is seamless, so it stops where it began */
+  @media (prefers-reduced-motion: no-preference) {
+    .pixel[data-tone="signal"] .pixel-title {
+      animation: pixel-rec var(--blink) steps(1, end) 4;
+    }
+    .scanlines::after {
+      animation: pixel-roll calc(var(--blink) * 4) steps(12, end);
+    }
+  }
+  @keyframes pixel-rec {
+    50% {
+      background: transparent;
+      color: var(--text-signal);
+    }
+  }
+  @keyframes pixel-roll {
+    to {
+      background-position: 0 12px;
+    }
+  }
+  .pixel:has(.pixel-title) {
+    margin-block-start: calc(var(--px) + 1em);
+    padding-block-start: var(--space-5);
+  }
+</style>

package/src/ui/Quote.astro

@@ -0,0 +1,49 @@
+---
+/** A quotation with its source: <figure><blockquote> + an optional cite line. */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"figure"> {
+  /** who or what said it */
+  cite?: string;
+  /** link to the source */
+  citeUrl?: string;
+  size?: "md" | "lg";
+}
+
+const { cite, citeUrl, size = "md", class: className, ...rest } = Astro.props;
+---
+
+<figure class:list={["quote", className]} data-size={size} {...rest}>
+  <blockquote cite={citeUrl}><slot /></blockquote>
+  {
+    cite && (
+      <figcaption class="label">
+        — {citeUrl ? <a href={citeUrl}><cite>{cite}</cite></a> : <cite>{cite}</cite>}
+      </figcaption>
+    )
+  }
+</figure>
+
+<style>
+  .quote {
+    display: grid;
+    gap: var(--space-3);
+    padding-inline-start: var(--space-5);
+    border-inline-start: 2px solid var(--fill-accent-strong);
+  }
+  blockquote {
+    color: var(--text-muted);
+    font-style: italic;
+  }
+  .quote[data-size="lg"] blockquote {
+    color: var(--text);
+    font-size: var(--step-2);
+    line-height: 1.35;
+  }
+  blockquote:is(:lang(fa), :lang(ar)) {
+    font-style: normal;
+  }
+  cite {
+    font-style: normal;
+  }
+</style>

package/src/ui/Tag.astro

@@ -0,0 +1,91 @@
+---
+/**
+ * A small tag. variant "chip": a bordered mono chip (project stacks) · "hash": an accent #tag link (post tags).
+ * Renders a link when `href` is set; `as="li"` lets a TagList item be the chip itself.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"a"> {
+  variant?: "chip" | "hash";
+  size?: "sm" | "md";
+  as?: "span" | "li";
+}
+
+const { variant = "chip", size = "sm", as = "span", href, class: className, ...rest } = Astro.props;
+const Tag = href ? "a" : as;
+---
+
+<Tag class:list={["tag", className]} data-variant={variant} data-size={size} href={href} {...rest}
+  >{variant === "hash" && <span class="hash" aria-hidden="true">#</span>}<slot /></Tag
+>
+
+<style>
+  .tag {
+    font-family: var(--font-mono);
+    font-size: var(--step--2);
+  }
+  /* mono has no Arabic script: use the Arabic face */
+  .tag:is(:lang(fa), :lang(ar)) {
+    font-family: var(--font-arabic);
+  }
+  .tag[data-size="md"] {
+    font-size: var(--step--1);
+  }
+  .tag[data-variant="chip"] {
+    padding: 0.1em 0.5em;
+    border: 1px solid var(--stroke);
+    border-radius: var(--radius);
+  }
+  /* a chip you can press draws its edge as a control (3:1); a plain chip keeps the hairline */
+  a.tag[data-variant="chip"] {
+    border-color: var(--stroke-control);
+    text-decoration: none;
+  }
+  /* drawn small, tapped big: a linked chip's hit area reaches --target-min in height (WCAG 2.5.5) */
+  a.tag {
+    position: relative;
+  }
+  a.tag::after {
+    content: "";
+    position: absolute;
+    inset-inline: 0;
+    inset-block: min(0px, (100% - var(--target-min)) / 2);
+  }
+  a.tag[data-variant="chip"]:hover {
+    border-color: var(--stroke-strong);
+    background: var(--state-hover);
+  }
+  a.tag[data-variant="chip"]:active {
+    background: var(--state-active);
+  }
+  a.tag[data-variant="hash"]:hover {
+    color: var(--text);
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    a.tag {
+      transition:
+        color var(--dur-step) var(--ease-step),
+        border-color var(--dur-step) var(--ease-step),
+        background-color var(--dur-step) var(--ease-step);
+    }
+    a.tag[data-variant="hash"]:hover .hash {
+      display: inline-block;
+      animation: tag-glitch calc(var(--dur-step) * 2) steps(1, end);
+    }
+  }
+  @keyframes tag-glitch {
+    0% {
+      translate: 0 -2px;
+    }
+    33% {
+      translate: 2px 0;
+    }
+    66% {
+      translate: -1px 1px;
+    }
+  }
+  .tag[data-variant="hash"] {
+    color: var(--text-accent);
+    text-decoration: none;
+  }
+</style>

package/src/ui/TagList.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * A wrapping list of Tags. Microformat classes go where each app already puts them:
+ * `itemClass` on the <li>, `linkClass` on the link (e.g. "p-category").
+ */
+import type { HTMLAttributes } from "astro/types";
+import Tag from "./Tag.astro";
+
+export interface TagItem {
+  label: string;
+  href?: string;
+}
+
+interface Props extends HTMLAttributes<"ul"> {
+  items: TagItem[];
+  variant?: "chip" | "hash";
+  size?: "sm" | "md";
+  /** accessible name of the list, e.g. "Tags" or "Stack" */
+  label: string;
+  itemClass?: string;
+  linkClass?: string;
+  /** rel on each link, e.g. "tag" */
+  rel?: string;
+}
+
+const {
+  items,
+  variant = "chip",
+  size = "sm",
+  label,
+  itemClass,
+  linkClass,
+  rel,
+  class: className,
+  ...rest
+} = Astro.props;
+---
+
+<ul class:list={["tag-list", className]} data-variant={variant} aria-label={label} {...rest}>
+  {
+    items.map((item) =>
+      item.href ? (
+        <li class={itemClass}>
+          <Tag variant={variant} size={size} href={item.href} class={linkClass} rel={rel}>
+            {item.label}
+          </Tag>
+        </li>
+      ) : (
+        <Tag as="li" variant={variant} size={size} class={itemClass}>
+          {item.label}
+        </Tag>
+      ),
+    )
+  }
+</ul>
+
+<style>
+  .tag-list {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-2);
+    list-style: none;
+    padding: 0;
+  }
+  .tag-list[data-variant="hash"] {
+    gap: var(--space-3);
+  }
+</style>

package/src/ui/Timeline.astro

@@ -0,0 +1,23 @@
+---
+/** A vertical dated list; fill it with <TimelineItem>s, newest first. */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"ol"> {
+  label?: string;
+}
+
+const { label, class: className, ...rest } = Astro.props;
+---
+
+<ol class:list={["timeline", className]} aria-label={label} {...rest}><slot /></ol>
+
+<style>
+  .timeline {
+    display: grid;
+    gap: var(--space-6);
+    list-style: none;
+    padding: 0;
+    padding-inline-start: var(--space-5);
+    border-inline-start: 1px dashed var(--stroke);
+  }
+</style>

package/src/ui/TimelineItem.astro

@@ -0,0 +1,105 @@
+---
+/**
+ * One step on a Timeline: a dated range, a title and an optional subtitle; body in the default slot.
+ * Marked up as an h-event (dt-start / dt-end). The end is for parsers only: `dates` already says it aloud.
+ * `href` links the title (e.g. an institution); slot "subtitle" takes markup the string prop can't (e.g. a p-location).
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"li"> {
+  title: string;
+  /** links the title */
+  href?: string;
+  subtitle?: string;
+  /** machine-readable start, e.g. "2021-03"; omit when only the end is known (the dates still show) */
+  start?: string;
+  /** machine-readable end; omit for "present" */
+  end?: string;
+  /** the dates as shown, e.g. "2021 — now" */
+  dates: string;
+  current?: boolean;
+  /** the title's heading level, so it fits the page outline (the Timeline usually sits under an h2) */
+  headingLevel?: 2 | 3 | 4;
+}
+
+const {
+  title,
+  href,
+  subtitle,
+  start,
+  end,
+  dates,
+  current = false,
+  headingLevel = 3,
+  class: className,
+  ...rest
+} = Astro.props;
+const Heading = `h${headingLevel}` as const;
+---
+
+<li class:list={["step h-event", className, { current }]} {...rest}>
+  <p class="label">
+    {start ? <time class="dt-start" datetime={start}>{dates}</time> : <span>{dates}</span>}
+    {end && <time class="dt-end" datetime={end} hidden />}
+  </p>
+  <Heading class="p-name">{href ? <a class="u-url" href={href}>{title}</a> : title}</Heading>
+  {
+    Astro.slots.has("subtitle") ? (
+      <p class="step-sub"><slot name="subtitle" /></p>
+    ) : (
+      subtitle && <p class="step-sub">{subtitle}</p>
+    )
+  }
+  {Astro.slots.has("default") && <div class="p-description step-body"><slot /></div>}
+</li>
+
+<style>
+  .step {
+    position: relative;
+    display: grid;
+    gap: var(--space-1);
+  }
+  /* the dot on the rail */
+  .step::before {
+    content: "";
+    position: absolute;
+    inset-inline-start: calc(-1 * var(--space-5) - 4px);
+    inset-block-start: 0.45em;
+    inline-size: 7px;
+    block-size: 7px;
+    border: 1px solid var(--fill-accent-strong);
+    border-radius: 50%;
+    background: var(--surface);
+  }
+  .current::before {
+    background: var(--text-accent);
+    box-shadow: 0 0 0 4px var(--fill-glow);
+  }
+  /* three pulses, under five seconds, then it holds (WCAG 2.2.2) */
+  @media (prefers-reduced-motion: no-preference) {
+    .current::before {
+      animation: step-blink calc(var(--blink) * 1.5) steps(1, end) 3;
+    }
+  }
+  @keyframes step-blink {
+    50% {
+      box-shadow: 0 0 0 2px var(--fill-glow);
+    }
+  }
+  .p-name {
+    font-size: var(--step-1);
+  }
+  .step-sub {
+    color: var(--text-accent);
+    font-style: italic;
+  }
+  .step-body {
+    color: var(--text-muted);
+    margin-block-start: var(--space-2);
+  }
+  /* 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/icons.ts

@@ -0,0 +1,27 @@
+/** Paths for <Icon>: a 24px grid, 1.5 stroke, round caps. Add an icon by adding a path. */
+export const PATHS = {
+  "arrow-right": "M4 12h15M13 6l6 6-6 6",
+  "arrow-left": "M20 12H5M11 6l-6 6 6 6",
+  "arrow-down": "M12 4v15M6 13l6 6 6-6",
+  "arrow-up": "M12 20V5M6 11l6-6 6 6",
+  download: "M12 4v11M7 10l5 5 5-5M5 20h14",
+  external: "M14 4h6v6M20 4l-9 9M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5",
+  "chevron-down": "M6 9l6 6 6-6",
+  "chevron-right": "M9 6l6 6-6 6",
+  close: "M6 6l12 12M18 6L6 18",
+  check: "M5 12.5l4.5 4.5L19 7",
+  info: "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM12 11v6M12 7.5v.01",
+  warning: "M12 3.5l9.5 16.5h-19L12 3.5zM12 10v4.5M12 17.5v.01",
+  search: "M10.5 18a7.5 7.5 0 1 0 0-15 7.5 7.5 0 0 0 0 15zM16 16l5 5",
+  copy: "M9 9h11v11H9zM5 15H4V4h11v1",
+  rss: "M5 5a14 14 0 0 1 14 14M5 11a8 8 0 0 1 8 8M6 19.01V19",
+  mail: "M3 6h18v12H3zM3 6l9 7 9-7",
+  github:
+    "M9 19c-4.5 1.4-4.5-2.5-6-3m12 5v-3.5c0-1 .1-1.4-.5-2 2.8-.3 5.5-1.4 5.5-6a4.6 4.6 0 0 0-1.3-3.2 4.2 4.2 0 0 0-.1-3.2s-1.1-.3-3.5 1.3a12 12 0 0 0-6.2 0C6.5 2.8 5.4 3.1 5.4 3.1a4.2 4.2 0 0 0-.1 3.2A4.6 4.6 0 0 0 4 9.5c0 4.6 2.7 5.7 5.5 6-.6.6-.6 1.2-.5 2V21",
+  moon: "M20 14.5A8.5 8.5 0 1 1 9.5 4a7 7 0 0 0 10.5 10.5z",
+  flower:
+    "M12 9a3 3 0 1 0 0 6 3 3 0 0 0 0-6zM12 9V4M12 15v5M9 12H4M15 12h5M9.9 9.9 6.3 6.3M14.1 14.1l3.6 3.6M14.1 9.9l3.6-3.6M9.9 14.1l-3.6 3.6",
+} as const;
+
+export type IconName = keyof typeof PATHS;
+export const ICON_NAMES = Object.keys(PATHS) as IconName[];