@cfasim-ui/docs 0.3.15 → 0.3.16

package/components/Container/Container.md

@@ -0,0 +1,103 @@
+# Container
+
+A flexible wrapper for grouping elements vertically (default) or horizontally. Optionally adds a border, fixed height with scrolling, and configurable gap between children.
+
+For multi-column layouts use [Grid](./grid).
+
+## Examples
+
+### Vertical stack (default)
+
+<ComponentDemo>
+  <Container gap="small">
+    <Box variant="info">First</Box>
+    <Box variant="info">Second</Box>
+    <Box variant="info">Third</Box>
+  </Container>
+
+<template #code>
+
+```vue
+<Container gap="small">
+  <Box variant="info">First</Box>
+  <Box variant="info">Second</Box>
+  <Box variant="info">Third</Box>
+</Container>
+```
+
+  </template>
+</ComponentDemo>
+
+### Horizontal row
+
+A row of buttons or chips. Wraps onto multiple lines when space runs out.
+
+<ComponentDemo>
+  <Container horizontal gap="small">
+    <Button>Save</Button>
+    <Button variant="secondary">Cancel</Button>
+    <Button variant="secondary">Reset</Button>
+  </Container>
+
+<template #code>
+
+```vue
+<Container horizontal gap="small">
+  <Button>Save</Button>
+  <Button variant="secondary">Cancel</Button>
+  <Button variant="secondary">Reset</Button>
+</Container>
+```
+
+  </template>
+</ComponentDemo>
+
+### Card with border
+
+<ComponentDemo>
+  <Container border gap="small">
+    <strong>Run summary</strong>
+    <span>Generated 1,000 samples in 2.4s</span>
+  </Container>
+
+<template #code>
+
+```vue
+<Container border gap="small">
+  <strong>Run summary</strong>
+  <span>Generated 1,000 samples in 2.4s</span>
+</Container>
+```
+
+  </template>
+</ComponentDemo>
+
+### Scrollable region
+
+Setting `height` automatically enables scrolling when content overflows.
+
+<ComponentDemo>
+  <Container border :height="180" gap="small">
+    <div v-for="i in 30" :key="i">Line {{ i }}</div>
+  </Container>
+
+<template #code>
+
+```vue
+<Container border :height="180" gap="small">
+  <div v-for="i in 30" :key="i">Line {{ i }}</div>
+</Container>
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `border` | `boolean` | No | — |
+| `height` | `number \| string` | No | — |
+| `horizontal` | `boolean` | No | — |
+| `gap` | `ContainerGap \| string` | No | — |
+

package/components/Container/Container.vue

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { type GapToken, resolveGap } from "../_internal/gap";
+
+export type ContainerGap = GapToken;
+
+const props = defineProps<{
+  border?: boolean;
+  height?: number | string;
+  horizontal?: boolean;
+  gap?: ContainerGap | string;
+}>();
+
+const resolvedGap = computed(() => resolveGap(props.gap));
+
+const resolvedHeight = computed(() => {
+  const h = props.height;
+  if (h == null) return undefined;
+  return typeof h === "number" ? `${h}px` : h;
+});
+</script>
+
+<template>
+  <div
+    class="container"
+    :class="{
+      'container-border': border,
+      'container-horizontal': horizontal,
+      'container-scrollable': height != null,
+    }"
+    :style="{
+      gap: resolvedGap,
+      height: resolvedHeight,
+    }"
+  >
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.container {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.container-horizontal {
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+.container-border {
+  padding: var(--space-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+}
+
+.container-scrollable {
+  overflow: auto;
+}
+</style>

package/components/Grid/Grid.md

@@ -0,0 +1,170 @@
+# Grid
+
+A CSS-grid wrapper for arranging elements in equal, proportional, or auto-fitting columns.
+
+For single-direction stacks (vertical or a flex row that wraps), use [Container](./container) instead.
+
+## Examples
+
+### Equal columns
+
+Pass a number for N equal-width columns.
+
+<ComponentDemo>
+  <Grid :cols="3" gap="medium">
+    <Box variant="info">Column 1</Box>
+    <Box variant="info">Column 2</Box>
+    <Box variant="info">Column 3</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="3" gap="medium">
+  <Box variant="info">Column 1</Box>
+  <Box variant="info">Column 2</Box>
+  <Box variant="info">Column 3</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Proportional widths
+
+Pass an array of `fr` weights for asymmetric layouts.
+
+<ComponentDemo>
+  <Grid :cols="[2, 3, 1]" gap="medium">
+    <Box variant="info">2fr</Box>
+    <Box variant="success">3fr</Box>
+    <Box variant="warning">1fr</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="[2, 3, 1]" gap="medium">
+  <Box variant="info">2fr</Box>
+  <Box variant="success">3fr</Box>
+  <Box variant="warning">1fr</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Mixed track sizes
+
+Strings pass through unchanged, so you can combine fixed and flexible tracks.
+
+<ComponentDemo>
+  <Grid :cols="['200px', '1fr']" gap="medium">
+    <Box variant="info">Fixed 200px</Box>
+    <Box variant="info">Fills remaining space</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="['200px', '1fr']" gap="medium">
+  <Box variant="info">Fixed 200px</Box>
+  <Box variant="info">Fills remaining space</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Small-width breakpoint
+
+`colsSmall` overrides `cols` when the grid's own width is at or below `breakpoint`. The default breakpoint is `640px` unless you specify it. The check is a CSS container query against the grid itself, so it triggers based on the grid's available width (e.g. when nested inside a sidebar), not the viewport.
+
+<ComponentDemo>
+  <Grid :cols="3" :cols-small="1" breakpoint="480px" gap="small">
+    <Box variant="info">Card 1</Box>
+    <Box variant="info">Card 2</Box>
+    <Box variant="info">Card 3</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="3" :cols-small="1" breakpoint="480px" gap="small">
+  <Box variant="info">Card 1</Box>
+  <Box variant="info">Card 2</Box>
+  <Box variant="info">Card 3</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Responsive auto-fit
+
+`minColWidth` switches to `repeat(auto-fit, minmax(...))` so items reflow to fit the viewport without media queries. Great for metric tiles and card grids.
+
+<ComponentDemo>
+  <Grid min-col-width="180px" gap="medium">
+    <Box variant="info">Card 1</Box>
+    <Box variant="info">Card 2</Box>
+    <Box variant="info">Card 3</Box>
+    <Box variant="info">Card 4</Box>
+    <Box variant="info">Card 5</Box>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid min-col-width="180px" gap="medium">
+  <Box variant="info">Card 1</Box>
+  <Box variant="info">Card 2</Box>
+  <Box variant="info">Card 3</Box>
+  <Box variant="info">Card 4</Box>
+  <Box variant="info">Card 5</Box>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+### Nested grids
+
+<ComponentDemo>
+  <Grid :cols="2" gap="medium">
+    <Box variant="info">Left</Box>
+    <Grid :cols="2" gap="small">
+      <Box variant="success">a</Box>
+      <Box variant="success">b</Box>
+      <Box variant="success">c</Box>
+      <Box variant="success">d</Box>
+    </Grid>
+  </Grid>
+
+<template #code>
+
+```vue
+<Grid :cols="2" gap="medium">
+  <Box variant="info">Left</Box>
+  <Grid :cols="2" gap="small">
+    <Box variant="success">a</Box>
+    <Box variant="success">b</Box>
+    <Box variant="success">c</Box>
+    <Box variant="success">d</Box>
+  </Grid>
+</Grid>
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `cols` | `GridCols` | No | — |
+| `colsSmall` | `GridCols` | No | — |
+| `breakpoint` | `string` | No | — |
+| `gap` | `GridGap \| string` | No | — |
+| `minColWidth` | `string` | No | — |
+

package/components/Grid/Grid.vue

@@ -0,0 +1,145 @@
+<script setup lang="ts">
+import { computed, onUnmounted, watch } from "vue";
+import { type GapToken, resolveGap } from "../_internal/gap";
+
+export type GridGap = GapToken;
+export type GridCols = number | (number | string)[];
+
+const props = defineProps<{
+  cols?: GridCols;
+  colsSmall?: GridCols;
+  breakpoint?: string;
+  gap?: GridGap | string;
+  minColWidth?: string;
+}>();
+
+const resolvedGap = computed(() => resolveGap(props.gap));
+
+const resolvedColumns = computed(() => {
+  if (props.minColWidth) {
+    return `repeat(auto-fit, minmax(${props.minColWidth}, 1fr))`;
+  }
+  return colsToTemplate(props.cols ?? 2);
+});
+
+const resolvedSmallColumns = computed(() => {
+  if (props.minColWidth || props.colsSmall == null) {
+    return resolvedColumns.value;
+  }
+  return colsToTemplate(props.colsSmall);
+});
+
+const safeBreakpoint = computed(() =>
+  sanitizeBreakpoint(props.breakpoint ?? DEFAULT_BREAKPOINT),
+);
+
+let acquired: string | null = null;
+const stopWatch = watch(
+  safeBreakpoint,
+  (next) => {
+    if (acquired === next) return;
+    acquireBreakpoint(next);
+    if (acquired) releaseBreakpoint(acquired);
+    acquired = next;
+  },
+  { immediate: true },
+);
+
+onUnmounted(() => {
+  stopWatch();
+  if (acquired) {
+    releaseBreakpoint(acquired);
+    acquired = null;
+  }
+});
+</script>
+
+<script lang="ts">
+const DEFAULT_BREAKPOINT = "640px";
+
+function colsToTemplate(cols: GridCols): string {
+  if (typeof cols === "number") return `repeat(${cols}, 1fr)`;
+  return cols.map((c) => (typeof c === "number" ? `${c}fr` : c)).join(" ");
+}
+
+// Allow only digits, dot, and unit letters/percent. Falls back to the default
+// when input doesn't look like a CSS length, preventing rule-escape via the
+// breakpoint prop.
+function sanitizeBreakpoint(value: string): string {
+  return /^\d+(\.\d+)?[a-zA-Z%]+$/.test(value) ? value : DEFAULT_BREAKPOINT;
+}
+
+// Module-scope cache: one <style> per unique breakpoint, ref-counted across
+// all Grid instances. The grid's inline `--grid-cols-small` is consumed by
+// the rule in the cached <style>.
+type Entry = { count: number; el: HTMLStyleElement };
+const breakpointSheets = new Map<string, Entry>();
+
+function acquireBreakpoint(breakpoint: string) {
+  if (typeof document === "undefined") return;
+  const existing = breakpointSheets.get(breakpoint);
+  if (existing) {
+    existing.count++;
+    return;
+  }
+  const el = document.createElement("style");
+  el.setAttribute("data-cfasim-grid-bp", breakpoint);
+  el.textContent =
+    `@container (max-width: ${breakpoint}) {` +
+    `[data-cfasim-grid-bp="${breakpoint}"] > .grid {` +
+    `grid-template-columns: var(--grid-cols-small) !important;` +
+    `}}`;
+  document.head.appendChild(el);
+  breakpointSheets.set(breakpoint, { count: 1, el });
+}
+
+function releaseBreakpoint(breakpoint: string) {
+  if (typeof document === "undefined") return;
+  const entry = breakpointSheets.get(breakpoint);
+  if (!entry) return;
+  entry.count--;
+  if (entry.count === 0) {
+    entry.el.remove();
+    breakpointSheets.delete(breakpoint);
+  }
+}
+
+const hmr = (import.meta as { hot?: { dispose: (cb: () => void) => void } })
+  .hot;
+hmr?.dispose(() => {
+  breakpointSheets.forEach(({ el }) => el.remove());
+  breakpointSheets.clear();
+});
+</script>
+
+<template>
+  <div :data-cfasim-grid-bp="safeBreakpoint" class="grid-wrapper">
+    <div
+      class="grid"
+      :style="{
+        gap: resolvedGap,
+        gridTemplateColumns: resolvedColumns,
+        '--grid-cols-small': resolvedSmallColumns,
+      }"
+    >
+      <slot />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.grid-wrapper {
+  container-type: inline-size;
+  width: 100%;
+  min-width: 0;
+}
+
+.grid {
+  display: grid;
+  min-width: 0;
+}
+
+.grid > :deep(*) {
+  min-width: 0;
+}
+</style>

package/components/_internal/gap.ts

@@ -0,0 +1,17 @@
+export type GapToken = "none" | "small" | "medium" | "large";
+
+const GAP_TOKENS: Record<GapToken, string> = {
+  none: "0",
+  small: "var(--space-2)",
+  medium: "var(--space-4)",
+  large: "var(--space-6)",
+};
+
+export function resolveGap(
+  gap: GapToken | string | undefined,
+  fallback: GapToken = "medium",
+): string {
+  if (gap == null) return GAP_TOKENS[fallback];
+  if (gap in GAP_TOKENS) return GAP_TOKENS[gap as GapToken];
+  return gap;
+}

package/components/index.ts

@@ -1,7 +1,11 @@
 export { default as Box } from "./Box/Box.vue";
 export type { BoxVariant } from "./Box/Box.vue";
 export { default as Button } from "./Button/Button.vue";
+export { default as Container } from "./Container/Container.vue";
+export type { ContainerGap } from "./Container/Container.vue";
 export { default as Expander } from "./Expander/Expander.vue";
+export { default as Grid } from "./Grid/Grid.vue";
+export type { GridCols, GridGap } from "./Grid/Grid.vue";
 export { default as Hint } from "./Hint/Hint.vue";
 export { default as Icon } from "./Icon/Icon.vue";
 export { default as LightDarkToggle } from "./LightDarkToggle/LightDarkToggle.vue";

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.15",
+  "version": "0.3.16",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [
@@ -23,6 +23,22 @@
           "secondary"
         ]
       },
+      {
+        "name": "Container",
+        "slug": "container",
+        "docs": "components/Container/Container.md",
+        "source": "components/Container/Container.vue",
+        "keywords": [
+          "container",
+          "layout",
+          "stack",
+          "row",
+          "flex",
+          "scrollable",
+          "border",
+          "card"
+        ]
+      },
       {
         "name": "Expander",
         "slug": "expander",
@@ -30,6 +46,22 @@
         "source": "components/Expander/Expander.vue",
         "keywords": []
       },
+      {
+        "name": "Grid",
+        "slug": "grid",
+        "docs": "components/Grid/Grid.md",
+        "source": "components/Grid/Grid.vue",
+        "keywords": [
+          "grid",
+          "columns",
+          "layout",
+          "responsive",
+          "auto-fit",
+          "cards",
+          "side-by-side",
+          "proportional"
+        ]
+      },
       {
         "name": "Hint",
         "slug": "hint",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {

package/theme/themes/cdc.css

@@ -8,6 +8,7 @@
   --font-weight-heading: 200;
   --font-size-md: 1.125rem;
   --font-size-2xl: 2.625rem;
+  --color-text: light-dark(#1c1d1f, #f8f9fa);
   --color-bg-0: light-dark(#ffffff, #0f1e21);
   --color-bg-1: light-dark(#f4fbfc, #162a2e);
   --color-bg-2: light-dark(#e9f5f8, #1e373c);
@@ -20,3 +21,15 @@
   --color-border-hover: light-dark(#a0d4e0, #3a5d64);
   --color-border-focus: var(--color-primary);
 }
+
+[data-theme="cdc"] a {
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.25rem;
+}
+
+[data-theme="cdc"] a:hover,
+[data-theme="cdc"] a:focus,
+[data-theme="cdc"] a:active {
+  color: light-dark(#007a99, #7dd6e8);
+}