@silvery/examples 0.5.2 → 0.5.3

package/layout/live-resize.tsx

@@ -0,0 +1,282 @@
+/**
+ * Live Resize Demo
+ *
+ * THE showcase demo for silvery's unique capability: components that know their size.
+ *
+ * Demonstrates:
+ * - useBoxRect() providing real-time width/height during render
+ * - Multi-column layout that reflows from 1 to 2 to 3 columns based on width
+ * - Responsive breakpoints with visual feedback
+ * - Content that adapts its presentation based on available space
+ * - No useEffect, no layout thrashing — dimensions are synchronous
+ *
+ * Usage: bun run examples/live-resize/index.tsx
+ *
+ * Try resizing your terminal to see the layout reflow in real-time!
+ *
+ * Controls:
+ *   Esc/q or Ctrl+C - Quit
+ */
+
+import React from "react"
+import { Box, Text, H1, H3, Kbd, Muted, Small, useBoxRect } from "silvery"
+import { run, useInput, type Key } from "silvery/runtime"
+import { useCallback } from "react"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Live Resize",
+  description: "Responsive multi-column grid that reflows based on terminal width",
+  features: ["useBoxRect()", "responsive breakpoints", "Box flexDirection"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface CardData {
+  title: string
+  icon: string
+  value: string
+  detail: string
+  color: string
+  sparkline: string
+}
+
+// ============================================================================
+// Data
+// ============================================================================
+
+const CARDS: CardData[] = [
+  {
+    title: "CPU Usage",
+    icon: "\u{1f4bb}",
+    value: "42%",
+    detail: "4 cores, 2.4 GHz base",
+    color: "green",
+    sparkline: "\u2582\u2583\u2585\u2587\u2586\u2584\u2583\u2585\u2587\u2588\u2586\u2584\u2583\u2582\u2583\u2585",
+  },
+  {
+    title: "Memory",
+    icon: "\u{1f9e0}",
+    value: "8.2 GB",
+    detail: "of 16 GB (51% used)",
+    color: "cyan",
+    sparkline: "\u2584\u2584\u2585\u2585\u2585\u2586\u2586\u2586\u2585\u2585\u2586\u2586\u2587\u2587\u2586\u2586",
+  },
+  {
+    title: "Disk I/O",
+    icon: "\u{1f4be}",
+    value: "234 MB/s",
+    detail: "Read: 180 MB/s Write: 54 MB/s",
+    color: "yellow",
+    sparkline: "\u2581\u2582\u2583\u2587\u2588\u2587\u2584\u2582\u2581\u2582\u2585\u2587\u2586\u2583\u2582\u2581",
+  },
+  {
+    title: "Network",
+    icon: "\u{1f310}",
+    value: "1.2 Gb/s",
+    detail: "In: 800 Mb/s Out: 400 Mb/s",
+    color: "magenta",
+    sparkline: "\u2583\u2584\u2585\u2586\u2587\u2586\u2585\u2584\u2585\u2586\u2587\u2588\u2587\u2586\u2585\u2584",
+  },
+  {
+    title: "Processes",
+    icon: "\u{2699}\u{fe0f}",
+    value: "247",
+    detail: "12 running, 235 sleeping",
+    color: "blue",
+    sparkline: "\u2585\u2585\u2585\u2586\u2585\u2585\u2585\u2585\u2586\u2585\u2585\u2585\u2586\u2585\u2585\u2585",
+  },
+  {
+    title: "Temperature",
+    icon: "\u{1f321}\u{fe0f}",
+    value: "62 C",
+    detail: "Max: 85 C (safe range)",
+    color: "red",
+    sparkline: "\u2583\u2583\u2584\u2584\u2585\u2585\u2586\u2586\u2585\u2585\u2584\u2584\u2583\u2584\u2585\u2585",
+  },
+]
+
+// ============================================================================
+// Components
+// ============================================================================
+
+function MetricCard({ card, compact }: { card: CardData; compact: boolean }) {
+  if (compact) {
+    // Minimal: single-line card for narrow terminals
+    return (
+      <Box borderStyle="round" borderColor={card.color} paddingX={1} flexDirection="row" justifyContent="space-between">
+        <H1 color={card.color}>{card.title}</H1>
+        <H3>{card.value}</H3>
+      </Box>
+    )
+  }
+
+  // Full card with sparkline and details
+  return (
+    <Box borderStyle="round" borderColor={card.color} paddingX={1} flexDirection="column" flexGrow={1}>
+      <Box justifyContent="space-between">
+        <H1 color={card.color}>{card.title}</H1>
+        <H1 color={card.color}>{card.value}</H1>
+      </Box>
+      <Text color={card.color}>{card.sparkline}</Text>
+      <Small>{card.detail}</Small>
+    </Box>
+  )
+}
+
+function BreakpointIndicator({ width, columns }: { width: number; columns: number }) {
+  const breakpoints = [
+    { threshold: 0, cols: 1, label: "< 60" },
+    { threshold: 60, cols: 2, label: "60-99" },
+    { threshold: 100, cols: 3, label: "100+" },
+  ]
+
+  return (
+    <Box gap={2} paddingX={1}>
+      {breakpoints.map((bp) => {
+        const isActive = bp.cols === columns
+        return (
+          <Box key={bp.cols} gap={1}>
+            <Text color={isActive ? "green" : "gray"} bold={isActive}>
+              {isActive ? "\u25cf" : "\u25cb"}
+            </Text>
+            <Text color={isActive ? "white" : "gray"} bold={isActive}>
+              {bp.cols} col{bp.cols > 1 ? "s" : " "} ({bp.label})
+            </Text>
+          </Box>
+        )
+      })}
+    </Box>
+  )
+}
+
+function GridLayout({ cards, columns, compact }: { cards: CardData[]; columns: number; compact: boolean }) {
+  if (columns === 1) {
+    return (
+      <Box flexDirection="column" gap={compact ? 0 : 1} flexGrow={1}>
+        {cards.map((card) => (
+          <MetricCard key={card.title} card={card} compact={compact} />
+        ))}
+      </Box>
+    )
+  }
+
+  // Build rows of N columns
+  const rows: CardData[][] = []
+  for (let i = 0; i < cards.length; i += columns) {
+    rows.push(cards.slice(i, i + columns))
+  }
+
+  return (
+    <Box flexDirection="column" gap={1} flexGrow={1}>
+      {rows.map((row, rowIndex) => (
+        <Box key={rowIndex} flexDirection="row" gap={1}>
+          {row.map((card) => (
+            <Box key={card.title} flexGrow={1} flexBasis={0}>
+              <MetricCard card={card} compact={false} />
+            </Box>
+          ))}
+          {/* Fill remaining slots for even spacing */}
+          {row.length < columns &&
+            Array.from({ length: columns - row.length }, (_, i) => (
+              <Box key={`spacer-${i}`} flexGrow={1} flexBasis={0} />
+            ))}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+function CodeSnippet({ width }: { width: number }) {
+  const showSnippet = width >= 60
+
+  if (!showSnippet) {
+    return (
+      <Box paddingX={1}>
+        <Text dim italic>
+          (Widen terminal to see the code that powers this)
+        </Text>
+      </Box>
+    )
+  }
+
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="$border" paddingX={1}>
+      <H1 color="yellow">How it works:</H1>
+      <Text color="gray">
+        {"  "}
+        <Text color="magenta">const</Text> {"{"} width {"}"} = <Text color="cyan">useBoxRect</Text>()
+      </Text>
+      <Text color="gray">
+        {"  "}
+        <Text color="magenta">const</Text> columns = width {">"} 100 ? <Text color="green">3</Text> : width {">"} 60 ?{" "}
+        <Text color="green">2</Text> : <Text color="green">1</Text>
+      </Text>
+      <Text dim italic>
+        {"  "}// No useEffect, no layout thrashing. Synchronous.
+      </Text>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main App
+// ============================================================================
+
+function LiveResize() {
+  const { width, height } = useBoxRect()
+
+  // Responsive breakpoints
+  const columns = width >= 100 ? 3 : width >= 60 ? 2 : 1
+  const compact = height < 20 || width < 40
+
+  useInput(
+    useCallback((input: string, key: Key) => {
+      if (input === "q" || key.escape || (key.ctrl && input === "c")) {
+        return "exit"
+      }
+    }, []),
+  )
+
+  return (
+    <Box flexDirection="column" width="100%" height="100%" padding={1}>
+      {/* Breakpoint indicator */}
+      <BreakpointIndicator width={width} columns={columns} />
+
+      {/* Main grid */}
+      <Box flexGrow={1} flexDirection="column" marginTop={1}>
+        <GridLayout cards={CARDS} columns={columns} compact={compact} />
+      </Box>
+
+      {/* Code snippet showing how it works */}
+      {!compact && <CodeSnippet width={width} />}
+
+      {/* Footer */}
+      <Box justifyContent="space-between" paddingX={1}>
+        <Muted>Resize your terminal to see the layout reflow</Muted>
+        <Muted>
+          <Kbd>Esc/q</Kbd> quit
+        </Muted>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  const handle = await run(
+    <ExampleBanner meta={meta} controls="Resize terminal to see reflow  Esc/q quit">
+      <LiveResize />
+    </ExampleBanner>,
+  )
+  await handle.waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/layout/overflow.tsx

@@ -0,0 +1,51 @@
+import React from "react"
+import { render, Box, Text, useApp, useInput, createTerm } from "silvery"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Overflow",
+  description: 'overflow="hidden" content clipping demonstration',
+  features: ['overflow="hidden"', "Box height"],
+}
+
+export function OverflowApp() {
+  const { exit } = useApp()
+  useInput((input, key) => {
+    if (input === "q" || key.escape) exit()
+  })
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="yellow">Title</Text>
+
+      <Box borderStyle="single" borderColor="$primary" height={5} overflow="hidden">
+        <Box flexDirection="column" flexGrow={1}>
+          <Text>Line 1</Text>
+          <Text>Line 2</Text>
+          <Text>Line 3</Text>
+          <Text>Line 4</Text>
+          <Text>Line 5</Text>
+          <Text>Line 6 - should NOT appear</Text>
+          <Text>Line 7 - should NOT appear</Text>
+        </Box>
+      </Box>
+
+      <Text color="$success">This should NOT be corrupted</Text>
+    </Box>
+  )
+}
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="Esc/q quit">
+      <OverflowApp />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/layout/text-layout.tsx

@@ -0,0 +1,283 @@
+/**
+ * Pretext Demo — snug-content bubbles + even wrapping comparison
+ *
+ * Interactive demo showcasing Silvery's Pretext-inspired text layout:
+ * - width="snug-content" — tightest box width for same line count (shrinkwrap)
+ * - wrap="even" — minimum-raggedness line breaking (Knuth-Plass)
+ *
+ * Inspired by https://chenglou.me/pretext/
+ *
+ * Usage: bun examples/pretext-demo.tsx
+ *
+ * Controls:
+ *   j/k - Cycle demo sections
+ *   Esc/q - Quit
+ */
+
+import React, { useState, useCallback } from "react"
+import { Box, Text, H2, Muted, Small, Kbd, Divider } from "silvery"
+import { run, useInput, type Key } from "silvery/runtime"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "text layout",
+  description: "Snug-content bubbles + even wrapping — inspired by chenglou/pretext",
+  demo: true,
+  features: ['width="snug-content"', 'wrap="even"', "chat bubbles", "paragraph layout"],
+}
+
+// ============================================================================
+// Sample Data
+// ============================================================================
+
+const CHAT_MESSAGES = [
+  { sender: "Alice", text: "Hey!" },
+  { sender: "Bob", text: "What are you working on?" },
+  { sender: "Alice", text: "Building a terminal UI framework with beautiful text layout." },
+  {
+    sender: "Bob",
+    text: "That sounds interesting. Does it handle word wrapping well? Most terminal apps have really ugly ragged text.",
+  },
+  {
+    sender: "Alice",
+    text: "Yes! It uses Pretext-inspired algorithms for snug bubbles and even line breaking.",
+  },
+]
+
+const PARAGRAPH =
+  "The quick brown fox jumps over the lazy dog. " +
+  "Typography in terminal applications has always been limited by the character grid, " +
+  "but modern algorithms can distribute text across lines for minimum raggedness, " +
+  "producing results that rival print-quality typesetting. " +
+  "Silvery brings these techniques to the terminal."
+
+// ============================================================================
+// Components
+// ============================================================================
+
+/** A single chat bubble with configurable width and wrap mode. */
+function Bubble({
+  sender,
+  text,
+  width,
+  wrap,
+  align,
+}: {
+  sender: string
+  text: string
+  width: "fit-content" | "snug-content"
+  wrap?: "wrap" | "even"
+  align?: "flex-start" | "flex-end"
+}) {
+  return (
+    <Box flexDirection="column" alignItems={align ?? "flex-start"}>
+      <Small> {sender}</Small>
+      <Box width={width} borderStyle="round" borderColor="$border" paddingX={1} maxWidth={48}>
+        <Text wrap={wrap ?? "wrap"}>{text}</Text>
+      </Box>
+    </Box>
+  )
+}
+
+/** Column of chat bubbles with a label. */
+function BubbleColumn({
+  label,
+  sublabel,
+  width,
+  wrap,
+}: {
+  label: string
+  sublabel: string
+  width: "fit-content" | "snug-content"
+  wrap?: "wrap" | "even"
+}) {
+  return (
+    <Box flexDirection="column" flexGrow={1} flexBasis={0}>
+      <Text bold color="$accent">
+        {label}
+      </Text>
+      <Muted>{sublabel}</Muted>
+      <Text> </Text>
+      <Box flexDirection="column" gap={1}>
+        {CHAT_MESSAGES.map((msg, i) => (
+          <Bubble
+            key={i}
+            sender={msg.sender}
+            text={msg.text}
+            width={width}
+            wrap={wrap}
+            align={msg.sender === "Bob" ? "flex-end" : "flex-start"}
+          />
+        ))}
+      </Box>
+    </Box>
+  )
+}
+
+/** Side-by-side paragraph comparison. */
+function ParagraphComparison({ label, sublabel, wrap }: { label: string; sublabel: string; wrap: "wrap" | "even" }) {
+  return (
+    <Box flexDirection="column" flexGrow={1} flexBasis={0}>
+      <Text bold color="$accent">
+        {label}
+      </Text>
+      <Muted>{sublabel}</Muted>
+      <Text> </Text>
+      <Box width={52} borderStyle="single" borderColor="$border" paddingX={1}>
+        <Text wrap={wrap}>{PARAGRAPH}</Text>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Demo Sections
+// ============================================================================
+
+function Demo1Bubbles() {
+  return (
+    <Box flexDirection="column">
+      <H2>Chat Bubbles: fit-content vs snug-content</H2>
+      <Muted>{"  "}fit-content sizes to the widest wrapped line (dead space on short lines).</Muted>
+      <Muted>{"  "}snug-content binary-searches for the tightest width with the same line count.</Muted>
+      <Text> </Text>
+      <Box flexDirection="row" gap={3} paddingX={1}>
+        <BubbleColumn label='width="fit-content"' sublabel="CSS default — dead space" width="fit-content" />
+        <BubbleColumn label='width="snug-content"' sublabel="Pretext shrinkwrap — tight" width="snug-content" />
+      </Box>
+    </Box>
+  )
+}
+
+function Demo2EvenWrap() {
+  return (
+    <Box flexDirection="column">
+      <H2>Paragraph Layout: greedy vs even wrapping</H2>
+      <Muted>{"  "}Greedy fills each line left-to-right, leaving a ragged right edge.</Muted>
+      <Muted>{"  "}Even uses minimum-raggedness DP to distribute words across all lines.</Muted>
+      <Text> </Text>
+      <Box flexDirection="row" gap={3} paddingX={1}>
+        <ParagraphComparison label='wrap="wrap"' sublabel="Greedy — ragged right edge" wrap="wrap" />
+        <ParagraphComparison label='wrap="even"' sublabel="Min-raggedness — balanced lines" wrap="even" />
+      </Box>
+    </Box>
+  )
+}
+
+function Demo3Combined() {
+  return (
+    <Box flexDirection="column">
+      <H2>Combined: snug-content + even wrapping</H2>
+      <Muted>{"  "}The tightest, most beautiful text layout — both features together.</Muted>
+      <Text> </Text>
+      <Box flexDirection="row" gap={3} paddingX={1}>
+        <Box flexDirection="column" flexGrow={1} flexBasis={0}>
+          <Text bold color="$accent">
+            Default (fit-content + greedy)
+          </Text>
+          <Muted>Widest line sets width, lines fill greedily</Muted>
+          <Text> </Text>
+          <Box flexDirection="column" gap={1}>
+            <Box width="fit-content" borderStyle="round" borderColor="$border" paddingX={1} maxWidth={48}>
+              <Text wrap="wrap">
+                Typography in terminal applications has always been limited by the character grid, but modern algorithms
+                change that.
+              </Text>
+            </Box>
+            <Box width="fit-content" borderStyle="round" borderColor="$border" paddingX={1} maxWidth={48}>
+              <Text wrap="wrap">Silvery brings Pretext-inspired layout to the terminal with two simple props.</Text>
+            </Box>
+          </Box>
+        </Box>
+        <Box flexDirection="column" flexGrow={1} flexBasis={0}>
+          <Text bold color="$accent">
+            Pretext (snug-content + even)
+          </Text>
+          <Muted>Tightest width, balanced line lengths</Muted>
+          <Text> </Text>
+          <Box flexDirection="column" gap={1}>
+            <Box width="snug-content" borderStyle="round" borderColor="$primary" paddingX={1} maxWidth={48}>
+              <Text wrap="even">
+                Typography in terminal applications has always been limited by the character grid, but modern algorithms
+                change that.
+              </Text>
+            </Box>
+            <Box width="snug-content" borderStyle="round" borderColor="$primary" paddingX={1} maxWidth={48}>
+              <Text wrap="even">Silvery brings Pretext-inspired layout to the terminal with two simple props.</Text>
+            </Box>
+          </Box>
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main App
+// ============================================================================
+
+const DEMOS = [Demo1Bubbles, Demo2EvenWrap, Demo3Combined]
+const DEMO_LABELS = ["Chat Bubbles", "Even Wrapping", "Combined"]
+
+function PretextDemo() {
+  const [demoIndex, setDemoIndex] = useState(0)
+
+  useInput(
+    useCallback((input: string, key: Key) => {
+      if (input === "q" || key.escape) return "exit"
+      if (input === "j" || key.downArrow || key.rightArrow) {
+        setDemoIndex((i) => Math.min(i + 1, DEMOS.length - 1))
+      }
+      if (input === "k" || key.upArrow || key.leftArrow) {
+        setDemoIndex((i) => Math.max(i - 1, 0))
+      }
+      if (input === "1") setDemoIndex(0)
+      if (input === "2") setDemoIndex(1)
+      if (input === "3") setDemoIndex(2)
+    }, []),
+  )
+
+  const Demo = DEMOS[demoIndex]!
+
+  return (
+    <Box flexDirection="column" padding={1} gap={1}>
+      {/* Tab bar */}
+      <Box gap={2}>
+        {DEMO_LABELS.map((label, i) => (
+          <Text key={i} bold={i === demoIndex} color={i === demoIndex ? "$primary" : "$muted"}>
+            {i === demoIndex ? "▸ " : "  "}
+            {i + 1}. {label}
+          </Text>
+        ))}
+      </Box>
+      <Divider />
+      {/* Active demo */}
+      <Demo />
+      {/* Footer */}
+      <Box>
+        <Muted>
+          {"  "}
+          <Kbd>j/k</Kbd> or <Kbd>1-3</Kbd> switch demo{"  "}
+          <Kbd>Esc/q</Kbd> quit
+        </Muted>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Entry Point
+// ============================================================================
+
+async function main() {
+  const handle = await run(
+    <ExampleBanner meta={meta} controls="j/k switch demo  1-3 jump  Esc/q quit">
+      <PretextDemo />
+    </ExampleBanner>,
+  )
+  await handle.waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/package.json

@@ -1,32 +1,48 @@
 {
   "name": "@silvery/examples",
-  "version": "0.5.2",
-  "description": "Example apps and component demos for silvery — bunx @silvery/examples <name>",
+  "version": "0.5.3",
+  "description": "Example apps and component demos for silvery — npx @silvery/examples <name>",
   "license": "MIT",
   "author": "Bjørn Stabell <bjorn@stabell.org>",
   "repository": {
     "type": "git",
     "url": "https://github.com/beorn/silvery.git",
-    "directory": "packages/examples"
+    "directory": "examples"
   },
+  "type": "module",
   "bin": {
-    "silvery-examples": "./bin/cli.ts"
+    "silvery-examples": "./dist/cli.mjs"
   },
   "files": [
-    "bin",
-    "examples"
+    "dist",
+    "components",
+    "apps",
+    "layout",
+    "runtime",
+    "inline",
+    "kitty",
+    "_banner.tsx"
   ],
-  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.mts",
+      "import": "./dist/cli.mjs"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
+  "tsdown": {
+    "entry": "bin/cli.ts",
+    "format": "esm",
+    "dts": true,
+    "clean": true
+  },
   "dependencies": {
-    "@silvery/ag-term": "0.5.0",
-    "@silvery/create": "0.5.0",
-    "silvery": "0.11.1"
+    "silvery": "0.17.1"
   },
   "engines": {
     "bun": ">=1.0",
     "node": ">=23.6.0"
   }
-}
+}