@karyl-chan/ui 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karyl-chan/ui",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared Vue UI primitives, composables, and design tokens used by karyl-chan's bot frontend and plugin webuis.",
   "type": "module",
   "license": "MIT",

package/src/components/AppConfirmDialog.vue

@@ -85,11 +85,9 @@ const emit = defineEmits<{
 </template>
 
 <style scoped>
-/* Inner wrapper: provides padding + flex-column layout + gap.
-   AppModal's body slots are structural-only (no padding), so each leaf
-   component is responsible for its own spacing. */
+/* Inner wrapper: flex-column layout + gap. Padding comes from
+   AppModal's body default. */
 .acd-body {
-    padding: 0.9rem 1rem 0.75rem;
     display: flex;
     flex-direction: column;
     gap: 0.75rem;

package/src/components/AppModal.vue

@@ -13,7 +13,11 @@ import { useDrawer } from '../composables/use-drawer';
  * The caller owns everything inside the slot — typical usage is to drop
  * a `<form @submit.prevent>` containing fields + an actions footer
  * directly into the default slot. AppModal supplies the chrome (backdrop,
- * panel, optional title header, close button) only.
+ * panel, optional title header, close button) and pads the body with
+ * `padding` (default `0.8rem 0.9rem`, both viewport branches). Slot
+ * content therefore needs no padding of its own; pass `padding="0"` for
+ * full-bleed content (tables, pickers, croppers) that manages its own
+ * edges.
  *
  * `closeOnBackdrop` / `closeOnEscape` default to true. Escape closure on
  * desktop is wired locally; on mobile it's handled by useDrawer's escape
@@ -27,11 +31,17 @@ const props = withDefaults(defineProps<{
     closeOnEscape?: boolean;
     /** Width of the desktop panel; mobile drawer ignores this. */
     width?: string;
+    /**
+     * CSS padding of the scrollable body around the default slot. Use
+     * `'0'` for full-bleed content that manages its own edges.
+     */
+    padding?: string;
 }>(), {
     title: '',
     closeOnBackdrop: true,
     closeOnEscape: true,
-    width: 'min(440px, 92vw)'
+    width: 'min(440px, 92vw)',
+    padding: '0.8rem 0.9rem'
 });
 
 const emit = defineEmits<{
@@ -101,7 +111,7 @@ function onBackdropClick() {
                             <Icon icon="material-symbols:close-rounded" width="18" height="18" />
                         </button>
                     </header>
-                    <div class="app-modal-body">
+                    <div class="app-modal-body" :style="{ padding }">
                         <slot />
                     </div>
                 </div>
@@ -141,7 +151,7 @@ function onBackdropClick() {
                         <Icon icon="material-symbols:close-rounded" width="18" height="18" />
                     </button>
                 </header>
-                <div class="app-modal-drawer-body">
+                <div class="app-modal-drawer-body" :style="{ padding }">
                     <slot />
                 </div>
             </div>
@@ -245,9 +255,8 @@ function onBackdropClick() {
 
 /* ── Desktop body wrapper ───────────────────────────────────────── */
 /* Structural wrapper that matches the mobile .app-modal-drawer-body.
-   Padding is intentionally 0 — callers are responsible for spacing
-   their slot content. AppConfirmDialog and similar leaf components
-   supply their own inner padding. */
+   Padding comes from the `padding` prop (inline style) on both
+   branches so slot content needs none of its own. */
 .app-modal-body {
     flex: 1;
     min-height: 0;

package/src/components/AppTabs.vue

@@ -32,10 +32,19 @@ const props = withDefaults(defineProps<{
     subTabs?: TabDef[];
     /** Where sub-tabs render on desktop. Has no effect on mobile. */
     subLayout?: 'top' | 'sidebar';
+    /**
+     * Primary-tab appearance (desktop only — mobile always uses the
+     * dropdown). `'pill'` (default) = filled/bordered pill buttons;
+     * `'underline'` = borderless tabs with an accent underline on the
+     * active one (the quieter, header-strip look). Sub-tabs are always
+     * underline-styled regardless.
+     */
+    variant?: 'pill' | 'underline';
 }>(), {
     subModelValue: undefined,
     subTabs: () => [],
-    subLayout: 'top'
+    subLayout: 'top',
+    variant: 'pill'
 });
 
 const emit = defineEmits<{
@@ -82,7 +91,7 @@ const subOptions = computed<SelectOption<string>[]>(() =>
     <!-- Desktop, sub-tabs below primary. -->
     <div
         v-else-if="!hasSub || subLayout === 'top'"
-        class="tabs-root desktop top"
+        :class="['tabs-root', 'desktop', 'top', { underline: variant === 'underline' }]"
     >
         <nav class="primary-row" role="tablist">
             <button
@@ -120,7 +129,7 @@ const subOptions = computed<SelectOption<string>[]>(() =>
     </div>
 
     <!-- Desktop, sub-tabs as a vertical sidebar. -->
-    <div v-else class="tabs-root desktop sidebar">
+    <div v-else :class="['tabs-root', 'desktop', 'sidebar', { underline: variant === 'underline' }]">
         <nav class="primary-row" role="tablist">
             <button
                 v-for="t in tabs"
@@ -213,6 +222,34 @@ const subOptions = computed<SelectOption<string>[]>(() =>
 }
 .tab:disabled { opacity: 0.45; cursor: default; }
 
+/* Underline variant — borderless primary tabs with an accent underline on
+   the active one (mirrors the plugin-aktest nav strip and the sub-tab
+   treatment). Railless: the row drops its bottom border so each tab owns
+   its own indicator. */
+.tabs-root.underline .primary-row {
+    border-bottom: none;
+    padding-bottom: 0;
+    gap: 0.15rem;
+}
+.tabs-root.underline .tab {
+    background: none;
+    border: none;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    color: var(--text-muted);
+    padding: 0.45rem 0.6rem;
+}
+.tabs-root.underline .tab:hover:not(:disabled) {
+    background: none;
+    color: var(--text);
+}
+.tabs-root.underline .tab.active {
+    background: none;
+    border-color: transparent;
+    border-bottom-color: var(--accent);
+    color: var(--accent-text-strong);
+}
+
 .sub-row {
     display: flex;
     gap: 0.6rem;

package/src/components/AppTabsRouted.vue

@@ -36,11 +36,16 @@ const props = withDefaults(defineProps<{
      *  routed AppTabs share a page. Empty (default) = plain `tab` /
      *  `sub`; non-empty = `${name}-tab` / `${name}-sub`. */
     name?: string;
+    /** Primary-tab appearance (desktop only). `'pill'` (default) = filled
+     *  pill buttons; `'underline'` = borderless with an accent underline on
+     *  the active tab. Matches AppTabs' `variant`. */
+    variant?: 'pill' | 'underline';
 }>(), {
     subModelValue: undefined,
     subTabs: () => [],
     subLayout: 'top',
-    name: ''
+    name: '',
+    variant: 'pill'
 });
 
 const emit = defineEmits<{
@@ -154,7 +159,7 @@ function subLinkTo(key: string) {
     <!-- Desktop, sub-tabs below primary. -->
     <div
         v-else-if="!hasSub || subLayout === 'top'"
-        class="tabs-root desktop top"
+        :class="['tabs-root', 'desktop', 'top', { underline: variant === 'underline' }]"
     >
         <nav class="primary-row" role="tablist">
             <template v-for="t in tabs" :key="t.key">
@@ -212,7 +217,7 @@ function subLinkTo(key: string) {
     </div>
 
     <!-- Desktop, sub-tabs as a vertical sidebar. -->
-    <div v-else class="tabs-root desktop sidebar">
+    <div v-else :class="['tabs-root', 'desktop', 'sidebar', { underline: variant === 'underline' }]">
         <nav class="primary-row" role="tablist">
             <template v-for="t in tabs" :key="t.key">
                 <RouterLink
@@ -313,6 +318,31 @@ function subLinkTo(key: string) {
 }
 .tab:disabled { opacity: 0.45; cursor: default; }
 
+/* Underline variant — see AppTabs.vue. Kept in sync with its plain sibling. */
+.tabs-root.underline .primary-row {
+    border-bottom: none;
+    padding-bottom: 0;
+    gap: 0.15rem;
+}
+.tabs-root.underline .tab {
+    background: none;
+    border: none;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    color: var(--text-muted);
+    padding: 0.45rem 0.6rem;
+}
+.tabs-root.underline .tab:hover:not(:disabled) {
+    background: none;
+    color: var(--text);
+}
+.tabs-root.underline .tab.active {
+    background: none;
+    border-color: transparent;
+    border-bottom-color: var(--accent);
+    color: var(--accent-text-strong);
+}
+
 .sub-row {
     display: flex;
     gap: 0.6rem;

package/src/components/Cluster.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/**
+ * Cluster — a horizontal group that wraps, owning the gap between items.
+ *
+ * For toolbars, tag/badge rows, button groups — anywhere items flow
+ * horizontally and should wrap rather than overflow. Defaults to
+ * vertically-centered, wrapping items. Pair with <Spacer /> to push a
+ * trailing item to the end instead of a one-off `margin-left:auto`:
+ *
+ *   <Cluster>
+ *     <h2>Title</h2>
+ *     <Spacer />
+ *     <AppButton>Action</AppButton>
+ *   </Cluster>
+ *
+ * `gap` takes a spacing-scale step (0–8 → --space-*) or a raw CSS length.
+ */
+import { computed, type CSSProperties } from "vue";
+import {
+  resolveSpace,
+  ALIGN_ITEMS,
+  JUSTIFY_CONTENT,
+  type Align,
+  type Justify,
+} from "../lib/space";
+
+const props = withDefaults(
+  defineProps<{
+    gap?: string | number;
+    align?: Align;
+    justify?: Justify;
+    /** Wrap onto multiple lines when items don't fit. On by default —
+     *  that's the whole point of a cluster. */
+    wrap?: boolean;
+  }>(),
+  {
+    gap: 3,
+    align: "center",
+    justify: "start",
+    wrap: true,
+  },
+);
+
+const style = computed<CSSProperties>(() => ({
+  display: "flex",
+  flexWrap: props.wrap ? "wrap" : "nowrap",
+  gap: resolveSpace(props.gap),
+  alignItems: ALIGN_ITEMS[props.align],
+  justifyContent: JUSTIFY_CONTENT[props.justify],
+}));
+</script>
+
+<template>
+  <div class="ui-cluster" :style="style"><slot /></div>
+</template>
+
+<style scoped>
+.ui-cluster { min-width: 0; }
+</style>

package/src/components/Spacer.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+/**
+ * Spacer — an empty flex-grow filler that pushes its siblings apart
+ * inside a Stack / Cluster (or any flex container), replacing the
+ * one-off `margin-left:auto` / `margin-top:auto` idiom:
+ *
+ *   <Cluster>
+ *     <Title />
+ *     <Spacer />   <!-- eats the free space -->
+ *     <Actions />
+ *   </Cluster>
+ *
+ * Purely presentational, so it's hidden from the accessibility tree.
+ */
+</script>
+
+<template>
+  <div class="ui-spacer" aria-hidden="true"></div>
+</template>
+
+<style scoped>
+.ui-spacer { flex: 1 1 auto; }
+</style>

package/src/components/Stack.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+/**
+ * Stack — a flex layout that OWNS the gap between its children.
+ *
+ * Reach for this instead of hand-authoring `display:flex; flex-direction:
+ * column; gap:…` (or per-element margins) in a view's scoped CSS — that
+ * pattern appears hundreds of times across the app and is exactly the
+ * responsibility a layout primitive should carry, not each component.
+ * Because the parent Stack owns the spacing, the components inside it
+ * never need (or should have) outer margins of their own.
+ *
+ *   <Stack gap="4">           vertical, 1rem gaps (--space-4)
+ *     <VoiceCard />
+ *     <AppTabs ... />
+ *     <section>…</section>
+ *   </Stack>
+ *
+ * `gap` takes a spacing-scale step (0–8 → --space-*) or a raw CSS length.
+ */
+import { computed, type CSSProperties } from "vue";
+import {
+  resolveSpace,
+  ALIGN_ITEMS,
+  JUSTIFY_CONTENT,
+  type Align,
+  type Justify,
+} from "../lib/space";
+
+const props = withDefaults(
+  defineProps<{
+    /** Gap between children: a scale step (0–8) or a raw CSS length. */
+    gap?: string | number;
+    /** Main-axis direction. Default vertical. */
+    direction?: "column" | "row";
+    align?: Align;
+    justify?: Justify;
+    /** Allow children to wrap onto multiple lines. */
+    wrap?: boolean;
+    /** Render as inline-flex (shrink-to-content) instead of flex. */
+    inline?: boolean;
+  }>(),
+  {
+    gap: 4,
+    direction: "column",
+    align: "stretch",
+    justify: "start",
+    wrap: false,
+    inline: false,
+  },
+);
+
+const style = computed<CSSProperties>(() => ({
+  display: props.inline ? "inline-flex" : "flex",
+  flexDirection: props.direction,
+  gap: resolveSpace(props.gap),
+  alignItems: ALIGN_ITEMS[props.align],
+  justifyContent: JUSTIFY_CONTENT[props.justify],
+  flexWrap: props.wrap ? "wrap" : "nowrap",
+}));
+</script>
+
+<template>
+  <div class="ui-stack" :style="style"><slot /></div>
+</template>
+
+<style scoped>
+/* min-width:0 lets a column stack's children (e.g. text) truncate instead
+   of forcing the stack wider than its parent. */
+.ui-stack { min-width: 0; }
+</style>

package/src/index.ts

@@ -7,6 +7,19 @@
 //   import "@karyl-chan/ui/use-drawer.css";
 //   import "@karyl-chan/ui/use-popover.css";
 
+// ── Layout primitives ────────────────────────────────────────────────────
+// Own the space BETWEEN elements so views (and the components inside them)
+// don't hand-author flex+gap or per-element margins. See lib/space.ts for
+// the `gap` scale.
+export { default as Stack } from "./components/Stack.vue";
+export { default as Cluster } from "./components/Cluster.vue";
+export { default as Spacer } from "./components/Spacer.vue";
+export {
+  resolveSpace,
+  type Align,
+  type Justify,
+} from "./lib/space";
+
 // ── Components ───────────────────────────────────────────────────────────
 export { default as AppBadge } from "./components/AppBadge.vue";
 export type { BadgeSize, BadgeTone, BadgeVariant } from "./components/AppBadge.vue";

package/src/lib/space.ts

@@ -0,0 +1,44 @@
+/**
+ * Spacing helpers for the layout primitives (Stack / Cluster / Spacer).
+ *
+ * `gap` and friends take a spacing-scale STEP (0–8, as a number or
+ * string) which maps to the corresponding `--space-*` token defined in
+ * tokens.css, or a raw CSS length (e.g. `"2px"`, `"1.5rem"`) as an
+ * escape hatch. Keeping the scale in tokens.css means the whole app
+ * shares one rhythm instead of 200 hand-picked gap values.
+ */
+
+/** Steps that exist as `--space-N` tokens in tokens.css. */
+const STEPS = new Set(["0", "1", "2", "3", "4", "5", "6", "7", "8"]);
+
+/** Resolve a gap/space prop to a CSS length: a scale step → `var(--space-N)`,
+ *  anything else → the value verbatim (raw CSS length escape hatch). */
+export function resolveSpace(
+  value: string | number | undefined,
+  fallback = "0",
+): string {
+  if (value === undefined || value === null || value === "") return fallback;
+  const s = String(value);
+  return STEPS.has(s) ? `var(--space-${s})` : s;
+}
+
+export type Align = "start" | "center" | "end" | "stretch" | "baseline";
+export type Justify = "start" | "center" | "end" | "between" | "around";
+
+/** Friendly `align` prop → CSS `align-items` value. */
+export const ALIGN_ITEMS: Record<Align, string> = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch",
+  baseline: "baseline",
+};
+
+/** Friendly `justify` prop → CSS `justify-content` value. */
+export const JUSTIFY_CONTENT: Record<Justify, string> = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between",
+  around: "space-around",
+};

package/src/tokens.css

@@ -66,6 +66,21 @@
     --radius-lg: 8px;
     --radius-xl: 12px;
     --radius-pill: 999px;
+
+    /* Spacing scale — the single source of truth for gaps between
+     * elements. Consume via the <Stack> / <Cluster> layout primitives
+     * (gap="4") rather than hand-authoring margins/gaps per view, so
+     * inter-element rhythm is owned by the layout layer, not by each
+     * component. Theme-independent (spacing doesn't change light/dark). */
+    --space-0: 0;
+    --space-1: 0.25rem;
+    --space-2: 0.5rem;
+    --space-3: 0.75rem;
+    --space-4: 1rem;
+    --space-5: 1.5rem;
+    --space-6: 2rem;
+    --space-7: 3rem;
+    --space-8: 4rem;
 }
 
 /* Pin the UA-side color-scheme hint so native widgets (form controls,