@ternent/core 0.0.1

package/packages/ui/src/patterns/PreviewPanel/PreviewPanel.vue

@@ -0,0 +1,354 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import Badge from "../../primitives/Badge/Badge.vue";
+import Card from "../../primitives/Card/Card.vue";
+import type {
+  PreviewPanelBadgeMode,
+  PreviewPanelEmphasis,
+  PreviewPanelRow,
+  PreviewPanelTone,
+} from "./PreviewPanel.types.js";
+
+const props = withDefaults(
+  defineProps<{
+    activeTab?: string;
+    badgeMode?: PreviewPanelBadgeMode;
+    code?: string;
+    emphasis?: PreviewPanelEmphasis;
+    footerLabel?: string;
+    footerText?: string;
+    footerTone?: PreviewPanelTone;
+    meta?: string;
+    rows?: readonly PreviewPanelRow[];
+    statusLabel?: string;
+    statusTone?: PreviewPanelTone;
+    tabs?: readonly string[];
+    title?: string;
+  }>(),
+  {
+    activeTab: undefined,
+    badgeMode: "default",
+    code: undefined,
+    emphasis: "default",
+    footerLabel: undefined,
+    footerText: undefined,
+    footerTone: "neutral",
+    meta: undefined,
+    rows: undefined,
+    statusLabel: undefined,
+    statusTone: "neutral",
+    tabs: undefined,
+    title: undefined,
+  },
+);
+
+const hasFooter = computed(() => Boolean(props.footerLabel || props.footerText));
+const toneClass = (tone?: PreviewPanelTone) =>
+  tone ? `ui-preview-panel__value--${tone}` : undefined;
+const rootClass = computed(() => ["ui-preview-panel", `ui-preview-panel--${props.emphasis}`]);
+const badgeVariant = computed(() => (props.badgeMode === "quiet" ? "outline" : "soft"));
+const badgeTone = (tone?: PreviewPanelTone) => (tone === "info" ? "primary" : tone);
+</script>
+
+<template>
+  <Card :class="rootClass" variant="panel" padding="md">
+    <div v-if="props.tabs?.length" class="ui-preview-panel__tabs" aria-hidden="true">
+      <span
+        v-for="tab in props.tabs"
+        :key="tab"
+        class="ui-preview-panel__tab"
+        :data-active="tab === props.activeTab"
+      >
+        {{ tab }}
+      </span>
+    </div>
+
+    <div v-if="props.title || props.statusLabel || props.meta" class="ui-preview-panel__header">
+      <div class="ui-preview-panel__heading">
+        <h3 v-if="props.title" class="ui-preview-panel__title">{{ props.title }}</h3>
+      </div>
+      <Badge
+        v-if="props.statusLabel"
+        :tone="badgeTone(props.statusTone)"
+        :variant="badgeVariant"
+        size="sm"
+      >
+        {{ props.statusLabel }}
+      </Badge>
+      <span v-else-if="props.meta" class="ui-preview-panel__meta">{{ props.meta }}</span>
+    </div>
+
+    <div class="ui-preview-panel__body">
+      <dl v-if="props.rows?.length" class="ui-preview-panel__rows">
+        <div v-for="row in props.rows" :key="row.label" class="ui-preview-panel__row">
+          <dt class="ui-preview-panel__label">{{ row.label }}</dt>
+          <dd class="ui-preview-panel__value" :class="toneClass(row.valueTone)">
+            {{ row.value }}
+          </dd>
+        </div>
+      </dl>
+
+      <pre v-else-if="props.code" class="ui-preview-panel__code"><code>{{ props.code }}</code></pre>
+
+      <div v-else class="ui-preview-panel__slot">
+        <slot />
+      </div>
+    </div>
+
+    <div v-if="hasFooter" class="ui-preview-panel__footer">
+      <Badge
+        v-if="props.footerLabel"
+        :tone="badgeTone(props.footerTone)"
+        :variant="badgeVariant"
+        size="sm"
+      >
+        {{ props.footerLabel }}
+      </Badge>
+      <p v-if="props.footerText" class="ui-preview-panel__footer-text">
+        {{ props.footerText }}
+      </p>
+    </div>
+  </Card>
+</template>
+
+<style scoped>
+.ui-preview-panel {
+  position: relative;
+  width: 100%;
+  max-width: 100%;
+  overflow: hidden;
+}
+
+.ui-preview-panel::before {
+  position: absolute;
+  inset: 0;
+  content: "";
+  background:
+    linear-gradient(
+      180deg,
+      color-mix(in srgb, var(--ui-tonal-tertiary) 78%, transparent),
+      transparent 28%
+    ),
+    radial-gradient(
+      circle at top right,
+      color-mix(in srgb, var(--ui-primary-muted) 38%, transparent),
+      transparent 38%
+    );
+  opacity: 0.42;
+  pointer-events: none;
+}
+
+.ui-preview-panel--subtle::before {
+  opacity: 0.22;
+}
+
+.ui-preview-panel--strong::before {
+  opacity: 0.34;
+}
+
+.ui-preview-panel::after {
+  position: absolute;
+  inset: 0;
+  content: "";
+  border-radius: inherit;
+  background-image:
+    linear-gradient(color-mix(in srgb, var(--ui-border) 72%, transparent) 1px, transparent 1px),
+    linear-gradient(
+      90deg,
+      color-mix(in srgb, var(--ui-border) 72%, transparent) 1px,
+      transparent 1px
+    );
+  background-position: center;
+  background-size: 2.25rem 2.25rem;
+  mask-image: radial-gradient(circle at center, black, transparent 78%);
+  opacity: 0.12;
+  pointer-events: none;
+}
+
+.ui-preview-panel--subtle::after {
+  opacity: 0.12;
+}
+
+.ui-preview-panel--strong::after {
+  opacity: 0.18;
+}
+
+.ui-preview-panel--strong {
+  box-shadow:
+    inset 0 0 0 1px color-mix(in srgb, var(--ui-border) 84%, transparent),
+    0 14px 30px color-mix(in srgb, var(--ui-bg) 55%, transparent);
+}
+
+.ui-preview-panel > * {
+  position: relative;
+  z-index: 1;
+}
+
+.ui-preview-panel__tabs {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  margin-bottom: 1rem;
+  padding: 0.25rem;
+  border: 1px solid var(--ui-border);
+  border-radius: calc(var(--ui-radius-md) + 4px);
+  background: color-mix(in srgb, var(--ui-surface) 72%, transparent);
+}
+
+.ui-preview-panel--strong .ui-preview-panel__tabs {
+  background: color-mix(in srgb, var(--ui-surface) 86%, transparent);
+}
+
+.ui-preview-panel__tab {
+  padding: 0.375rem 0.75rem;
+  border-radius: calc(var(--ui-radius-sm) + 2px);
+  color: var(--ui-fg-muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.ui-preview-panel__tab[data-active="true"] {
+  background: var(--ui-surface);
+  color: var(--ui-fg);
+  box-shadow: var(--ui-shadow-sm);
+}
+
+.ui-preview-panel--strong .ui-preview-panel__tab[data-active="true"] {
+  box-shadow:
+    inset 0 0 0 1px color-mix(in srgb, var(--ui-border) 86%, transparent),
+    var(--ui-shadow-sm);
+}
+
+.ui-preview-panel__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+.ui-preview-panel__title {
+  margin: 0;
+  color: var(--ui-fg);
+  font-size: 1.125rem;
+  font-weight: 500;
+  letter-spacing: -0.02em;
+}
+
+.ui-preview-panel--strong .ui-preview-panel__title {
+  font-size: 1.2rem;
+}
+
+.ui-preview-panel__meta {
+  color: var(--ui-fg-muted);
+  font-size: 0.8rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.ui-preview-panel__body {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  min-width: 0;
+}
+
+.ui-preview-panel__rows {
+  display: flex;
+  flex-direction: column;
+  gap: 0.875rem;
+  margin: 0;
+}
+
+.ui-preview-panel__row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding-bottom: 0.75rem;
+  border-bottom: 1px solid color-mix(in srgb, var(--ui-border) 72%, transparent);
+}
+
+.ui-preview-panel--strong .ui-preview-panel__row {
+  border-bottom-color: color-mix(in srgb, var(--ui-border) 88%, transparent);
+}
+
+.ui-preview-panel__row:last-child {
+  padding-bottom: 0;
+  border-bottom: 0;
+}
+
+.ui-preview-panel__label {
+  color: var(--ui-fg-muted);
+  font-size: 0.875rem;
+}
+
+.ui-preview-panel__value {
+  margin: 0;
+  color: var(--ui-fg);
+  font-size: 0.95rem;
+  font-weight: 500;
+  text-align: right;
+}
+
+.ui-preview-panel__value--primary,
+.ui-preview-panel__value--info {
+  color: var(--ui-primary);
+}
+
+.ui-preview-panel__value--secondary {
+  color: var(--ui-secondary);
+}
+
+.ui-preview-panel__value--accent,
+.ui-preview-panel__value--warning {
+  color: var(--ui-accent);
+}
+
+.ui-preview-panel__value--success {
+  color: var(--ui-success);
+}
+
+.ui-preview-panel__value--critical {
+  color: var(--ui-critical);
+}
+
+.ui-preview-panel__code {
+  margin: 0;
+  min-width: 0;
+  max-width: 100%;
+  padding: 1rem 1.125rem;
+  overflow-x: auto;
+  border: 1px solid color-mix(in srgb, var(--ui-border) 72%, transparent);
+  border-radius: var(--ui-radius-md);
+  background: color-mix(in srgb, var(--ui-bg) 55%, var(--ui-surface));
+  color: var(--ui-fg);
+  font-size: 0.92rem;
+  line-height: 1.8;
+}
+
+.ui-preview-panel--subtle .ui-preview-panel__code {
+  background: color-mix(in srgb, var(--ui-surface) 88%, var(--ui-bg));
+}
+
+.ui-preview-panel__slot {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  min-width: 0;
+}
+
+.ui-preview-panel__footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+  margin-top: 1.25rem;
+}
+
+.ui-preview-panel__footer-text {
+  margin: 0;
+  color: var(--ui-fg-muted);
+  font-size: 0.95rem;
+}
+</style>

package/packages/ui/src/patterns/RecordList/RecordList.spec.md

@@ -0,0 +1,35 @@
+# RecordList
+
+## Purpose
+
+Reusable selectable list composition for entity navigation and lightweight grouped records.
+
+## Category
+
+Pattern
+
+## Public API
+
+Props:
+
+- `items`: `RecordListItem[]`
+- `title`: optional section title
+- `emptyLabel`: empty-state copy (`No records yet.` default)
+- `defaultActionLabel`: optional fallback row action label
+- `surface`: `card | plain` (`card` default)
+
+Slots:
+
+- `item-action` scoped slot (`item`)
+
+Events:
+
+- `select(item, event)` when an item row is selected
+- `action(item, event)` default action button event
+
+## Behavior
+
+- composes `Card`, `Button`, and `Separator` primitives
+- highlights active item with secondary button treatment
+- supports per-item disabled behavior
+- renders explicit empty state when no items are available

package/packages/ui/src/patterns/RecordList/RecordList.test.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { RecordListItem } from "./RecordList.types";
+import { resolveRecordListSecondaryText } from "./RecordList.utils";
+
+describe("RecordList", () => {
+  it("resolves row secondary text from meta then description", () => {
+    const withMeta: RecordListItem = {
+      id: "one",
+      title: "One",
+      meta: "1 member",
+      description: "fallback",
+    };
+
+    const withDescription: RecordListItem = {
+      id: "two",
+      title: "Two",
+      description: "Description only",
+    };
+
+    const withNone: RecordListItem = {
+      id: "three",
+      title: "Three",
+    };
+
+    expect(resolveRecordListSecondaryText(withMeta)).toBe("1 member");
+    expect(resolveRecordListSecondaryText(withDescription)).toBe("Description only");
+    expect(resolveRecordListSecondaryText(withNone)).toBeNull();
+  });
+
+  it("declares item-action slot and empty-state affordance", () => {
+    const source = readFileSync(
+      resolve(process.cwd(), "src/patterns/RecordList/RecordList.vue"),
+      "utf8",
+    );
+
+    expect(source).toContain('<slot name="item-leading" :item="item" />');
+    expect(source).toContain('<slot name="item-action" :item="item">');
+    expect(source).toContain('data-test="record-list-empty"');
+  });
+});

package/packages/ui/src/patterns/RecordList/RecordList.types.ts

@@ -0,0 +1,9 @@
+export type RecordListItem = {
+  active?: boolean;
+  dataTest?: string;
+  description?: string;
+  disabled?: boolean;
+  id: string;
+  meta?: string;
+  title: string;
+};

package/packages/ui/src/patterns/RecordList/RecordList.utils.ts

@@ -0,0 +1,5 @@
+import type { RecordListItem } from "./RecordList.types";
+
+export function resolveRecordListSecondaryText(item: RecordListItem): string | null {
+  return item.meta ?? item.description ?? null;
+}

package/packages/ui/src/patterns/RecordList/RecordList.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import Button from "../../primitives/Button/Button.vue";
+import Card from "../../primitives/Card/Card.vue";
+import Separator from "../../primitives/Separator/Separator.vue";
+import type { RecordListItem } from "./RecordList.types";
+import { resolveRecordListSecondaryText } from "./RecordList.utils";
+
+const emit = defineEmits<{
+  action: [item: RecordListItem, event: MouseEvent];
+  select: [item: RecordListItem, event: MouseEvent];
+}>();
+
+const props = withDefaults(
+  defineProps<{
+    defaultActionLabel?: string;
+    emptyLabel?: string;
+    items: RecordListItem[];
+    surface?: "card" | "plain";
+    title?: string;
+  }>(),
+  {
+    defaultActionLabel: undefined,
+    emptyLabel: "No records yet.",
+    surface: "card",
+    title: undefined,
+  },
+);
+
+const normalizedItems = computed(() => props.items);
+
+function handleSelect(item: RecordListItem, event: MouseEvent): void {
+  if (item.disabled) {
+    event.preventDefault();
+    event.stopPropagation();
+    return;
+  }
+
+  emit("select", item, event);
+}
+
+function handleAction(item: RecordListItem, event: MouseEvent): void {
+  if (item.disabled) {
+    event.preventDefault();
+    event.stopPropagation();
+    return;
+  }
+
+  emit("action", item, event);
+}
+
+const wrapperClass = computed(() =>
+  props.surface === "card"
+    ? "flex h-full min-h-0 flex-col gap-2"
+    : "flex h-full min-h-0 flex-col gap-2 px-1",
+);
+</script>
+
+<template>
+  <component
+    :is="props.surface === 'card' ? Card : 'div'"
+    :variant="props.surface === 'card' ? 'outline' : undefined"
+    :padding="props.surface === 'card' ? 'sm' : undefined"
+    :class="wrapperClass"
+  >
+    <p
+      v-if="props.title"
+      class="m-0 px-1 text-xs uppercase tracking-[0.12em] text-[var(--ui-fg-muted)]"
+    >
+      {{ props.title }}
+    </p>
+
+    <div
+      v-if="normalizedItems.length === 0"
+      class="px-2 py-3 text-sm text-[var(--ui-fg-muted)]"
+      data-test="record-list-empty"
+    >
+      {{ props.emptyLabel }}
+    </div>
+
+    <ul
+      v-else
+      class="m-0 flex min-h-0 list-none flex-col gap-1 overflow-auto p-0"
+      data-test="record-list-items"
+    >
+      <li v-for="(item, index) in normalizedItems" :key="item.id" :data-test="item.dataTest">
+        <div class="flex items-center gap-2">
+          <Button
+            type="button"
+            size="sm"
+            :variant="item.active ? 'secondary' : 'plain-secondary'"
+            class="min-w-0 flex-1 justify-start"
+            :disabled="Boolean(item.disabled)"
+            :aria-current="item.active ? 'true' : undefined"
+            @click="handleSelect(item, $event)"
+          >
+            <span class="flex min-w-0 items-center gap-2 text-left">
+              <slot name="item-leading" :item="item" />
+              <span class="min-w-0">
+                <span class="block truncate text-sm">{{ item.title }}</span>
+                <span
+                  v-if="resolveRecordListSecondaryText(item)"
+                  class="block truncate text-xs text-[var(--ui-fg-muted)]"
+                >
+                  {{ resolveRecordListSecondaryText(item) }}
+                </span>
+              </span>
+            </span>
+          </Button>
+
+          <slot name="item-action" :item="item">
+            <Button
+              v-if="props.defaultActionLabel"
+              type="button"
+              variant="plain-secondary"
+              size="xs"
+              :disabled="Boolean(item.disabled)"
+              aria-label="Row action"
+              @click="handleAction(item, $event)"
+            >
+              {{ props.defaultActionLabel }}
+            </Button>
+          </slot>
+        </div>
+
+        <Separator
+          v-if="index < normalizedItems.length - 1"
+          orientation="horizontal"
+          class="my-2"
+        />
+      </li>
+    </ul>
+  </component>
+</template>

package/packages/ui/src/patterns/SectionClarifier/SectionClarifier.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    eyebrow?: string;
+    title: string;
+    titleTag?: "h2" | "h3";
+  }>(),
+  {
+    eyebrow: undefined,
+    titleTag: "h2",
+  },
+);
+</script>
+
+<template>
+  <section class="ui-section-clarifier">
+    <div class="ui-section-clarifier__header">
+      <p v-if="eyebrow" class="ui-section-clarifier__eyebrow">
+        {{ eyebrow }}
+      </p>
+      <component :is="titleTag" class="ui-section-clarifier__title">
+        {{ title }}
+      </component>
+    </div>
+
+    <div class="ui-section-clarifier__frame">
+      <div class="ui-section-clarifier__content">
+        <slot />
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.ui-section-clarifier {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  width: 100%;
+  margin-inline: auto;
+}
+
+.ui-section-clarifier__header {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.ui-section-clarifier__eyebrow {
+  margin: 0;
+  color: var(--ui-fg-muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+}
+
+.ui-section-clarifier__title {
+  margin: 0;
+  max-width: 30rem;
+  color: var(--ui-fg);
+  font-size: clamp(1.25rem, 1.8vw, 1.5rem);
+  font-weight: 500;
+  letter-spacing: -0.025em;
+  line-height: 1.16;
+  text-wrap: balance;
+}
+
+.ui-section-clarifier__frame {
+  border-top: 1px solid color-mix(in srgb, var(--ui-border) 82%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--ui-border) 82%, transparent);
+  background-color: color-mix(in srgb, var(--ui-bg) 84%, var(--ui-tonal-secondary) 16%);
+}
+
+.ui-section-clarifier__content {
+  min-width: 0;
+  padding: 1.5rem;
+}
+
+@media (min-width: 768px) {
+  .ui-section-clarifier__content {
+    padding: 1.75rem 2rem;
+  }
+}
+</style>

package/packages/ui/src/patterns/SectionIntro/SectionIntro.spec.md

@@ -0,0 +1,25 @@
+# SectionIntro
+
+## Purpose
+
+Shared heading block for hero, section, and supporting narrative copy.
+
+## Category
+
+Pattern
+
+## Public API
+
+Props:
+
+- `eyebrow`
+- `title`
+- `description`
+- `align`: `start | center`
+- `size`: `hero | section | compact`
+- `titleTag`: `h1 | h2 | h3`
+
+Slots:
+
+- default: additional content below the description
+- `actions`: action row for buttons or supporting controls

package/packages/ui/src/patterns/SectionIntro/SectionIntro.types.ts

@@ -0,0 +1,7 @@
+export const sectionIntroAlignValues = ["start", "center"] as const;
+export const sectionIntroSizeValues = ["hero", "section", "compact"] as const;
+export const sectionIntroTitleTagValues = ["h1", "h2", "h3"] as const;
+
+export type SectionIntroAlign = (typeof sectionIntroAlignValues)[number];
+export type SectionIntroSize = (typeof sectionIntroSizeValues)[number];
+export type SectionIntroTitleTag = (typeof sectionIntroTitleTagValues)[number];