@cfasim-ui/components 0.7.8 → 0.8.1

package/src/Container/Container.md

@@ -0,0 +1,99 @@
+---
+keywords: [container, layout, stack, row, flex, scrollable, border, card]
+---
+
+# 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>
+
+<!--@include: ./_api/container.md-->

package/src/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/src/Expander/Expander.md

@@ -0,0 +1,23 @@
+# Expander
+
+A collapsible section that toggles content visibility.
+
+## Examples
+
+<ComponentDemo>
+  <Expander label="Show advanced options">
+    <p style="margin: 0">Here is the hidden content.</p>
+  </Expander>
+
+<template #code>
+
+```vue
+<Expander label="Show advanced options">
+  <p>Here is the hidden content.</p>
+</Expander>
+```
+
+  </template>
+</ComponentDemo>
+
+<!--@include: ./_api/expander.md-->

package/src/Expander/Expander.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import {
+  CollapsibleRoot,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from "reka-ui";
+
+const open = defineModel<boolean>("open", { default: false });
+
+defineProps<{
+  label?: string;
+}>();
+</script>
+
+<template>
+  <CollapsibleRoot v-model:open="open" class="expander">
+    <CollapsibleTrigger class="expander-trigger">
+      <span class="expander-caret" :class="{ open }" />
+      <slot name="label">{{ label }}</slot>
+    </CollapsibleTrigger>
+    <CollapsibleContent class="expander-content">
+      <slot />
+    </CollapsibleContent>
+  </CollapsibleRoot>
+</template>
+
+<style scoped>
+.expander-trigger {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  width: 100%;
+  padding: 0.5em 0;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-secondary);
+}
+
+.expander-trigger:hover {
+  color: var(--color-text);
+}
+
+.expander-caret {
+  display: inline-block;
+  width: 0;
+  height: 0;
+  border-left: 0.35em solid currentColor;
+  border-top: 0.3em solid transparent;
+  border-bottom: 0.3em solid transparent;
+  transition: transform 0.15s;
+}
+
+.expander-caret.open {
+  transform: rotate(90deg);
+}
+
+.expander-content {
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75em;
+}
+
+.expander-content[data-state="open"] {
+  animation: slideDown 200ms ease-out;
+}
+
+.expander-content[data-state="closed"] {
+  animation: slideUp 200ms ease-out;
+}
+
+@keyframes slideDown {
+  from {
+    height: 0;
+  }
+  to {
+    height: var(--reka-collapsible-content-height);
+  }
+}
+
+@keyframes slideUp {
+  from {
+    height: var(--reka-collapsible-content-height);
+  }
+  to {
+    height: 0;
+  }
+}
+</style>

package/src/Grid/Grid.md

@@ -0,0 +1,175 @@
+---
+keywords:
+  [
+    grid,
+    columns,
+    layout,
+    responsive,
+    auto-fit,
+    cards,
+    side-by-side,
+    proportional,
+  ]
+---
+
+# 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>
+
+<!--@include: ./_api/grid.md-->

package/src/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/src/Hint/Hint.md

@@ -0,0 +1,24 @@
+# Hint
+
+An info icon that shows a tooltip on hover. Used alongside form labels to provide additional context.
+
+## Examples
+
+<ComponentDemo>
+  <span style="display: flex; align-items: center; gap: 8px;">
+    Population size <Hint text="The total number of individuals in the simulation." />
+  </span>
+
+<template #code>
+
+```vue
+<span style="display: flex; align-items: center; gap: 8px;">
+  Population size
+  <Hint text="The total number of individuals in the simulation." />
+</span>
+```
+
+  </template>
+</ComponentDemo>
+
+<!--@include: ./_api/hint.md-->

package/src/Hint/Hint.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import {
+  TooltipArrow,
+  TooltipContent,
+  TooltipPortal,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+} from "reka-ui";
+import Icon from "../Icon/Icon.vue";
+
+defineProps<{
+  text: string;
+}>();
+</script>
+
+<template>
+  <TooltipProvider>
+    <TooltipRoot :delay-duration="0" disable-closing-trigger>
+      <TooltipTrigger as-child>
+        <button
+          type="button"
+          class="HintTrigger"
+          aria-label="More info"
+          @pointerdown.prevent
+        >
+          <Icon icon="help" :size="16" />
+        </button>
+      </TooltipTrigger>
+      <TooltipPortal>
+        <TooltipContent class="HintContent" side="top" :side-offset="4">
+          {{ text }}
+          <TooltipArrow class="HintArrow" :width="10" :height="5" />
+        </TooltipContent>
+      </TooltipPortal>
+    </TooltipRoot>
+  </TooltipProvider>
+</template>
+
+<style scoped>
+.HintTrigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.25em;
+  height: 1.25em;
+  padding: 0;
+  margin: 0;
+  border: none;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+.HintTrigger:hover {
+  color: var(--color-text);
+}
+
+.HintTrigger:focus-visible {
+  outline: none;
+  box-shadow: var(--shadow-focus);
+}
+</style>
+
+<style>
+.HintContent {
+  max-width: 15rem;
+  padding: 0.5em 0.75em;
+  font-size: var(--font-size-xs);
+  line-height: 1.4;
+  color: var(--color-bg-0);
+  background-color: var(--color-text);
+  border-radius: 0.25em;
+  box-shadow: var(--shadow-md);
+  z-index: 100;
+}
+
+.HintArrow {
+  fill: var(--color-text);
+}
+</style>