@joshwilkerson/flex-ui 1.0.0-alpha.0

package/scripts/generate-flex-css.ts

@@ -0,0 +1,316 @@
+/**
+ * CLI wrapper for CSS generation
+ *
+ * Used by: npx flex-ui generate
+ * For consumers who want to generate CSS with custom config.
+ */
+
+import * as fs from "fs"
+import * as path from "path"
+import { fileURLToPath } from "url"
+import { pathToFileURL } from "url"
+import { type FlexConfig, defaultConfig, resolveSpacing } from "../src/config"
+import {
+  axis,
+  axisToDirection,
+  justify,
+  justifyToCSS,
+  align,
+  alignToCSS,
+  wrap,
+  alignContent,
+  alignContentToCSS,
+  alignSelf,
+  alignSelfToCSS,
+} from "../src/tokens"
+
+const GENERATED_HEADER = `/**
+ * Flex UI - CSS-only flexbox layouts
+ *
+ * Usage:
+ *   <div data-flex data-axis="horizontal" data-gap="2" data-align="center">
+ *     <div>Item 1</div>
+ *     <div>Item 2</div>
+ *   </div>
+ *
+ * Customize spacing by overriding CSS custom properties:
+ *   :root {
+ *     --flex-spacing-1: 0.5rem;
+ *     --flex-spacing-2: 1rem;
+ *   }
+ *
+ * Generated by: npx flex-ui generate
+ */
+
+`
+
+const CONFIG_FILES = [
+  "flex.config.ts",
+  "flex.config.js",
+  "flex.config.mjs",
+  "flex.config.json",
+]
+
+interface ResolvedConfig {
+  breakpoints: Record<string, number>
+  breakpointKeys: string[]
+  spacing: Record<string | number, string>
+  spacingKeys: (string | number)[]
+  output: string
+}
+
+async function loadConfig(cwd: string): Promise<FlexConfig> {
+  for (const filename of CONFIG_FILES) {
+    const configPath = path.join(cwd, filename)
+
+    if (!fs.existsSync(configPath)) {
+      continue
+    }
+
+    console.log(`Found config: ${filename}`)
+
+    if (filename.endsWith(".json")) {
+      const content = fs.readFileSync(configPath, "utf-8")
+      return JSON.parse(content) as FlexConfig
+    }
+
+    const fileUrl = pathToFileURL(configPath).href
+    const module = await import(fileUrl)
+    return (module.default || module) as FlexConfig
+  }
+
+  return {}
+}
+
+function mergeConfig(userConfig: FlexConfig): ResolvedConfig {
+  const breakpoints: Record<string, number> = userConfig.breakpoints ?? {
+    ...defaultConfig.breakpoints,
+  }
+  const spacingConfig = userConfig.spacing ?? defaultConfig.spacing
+  const spacing = resolveSpacing(spacingConfig)
+
+  return {
+    breakpoints,
+    breakpointKeys: Object.keys(breakpoints).sort(
+      (a, b) => breakpoints[a] - breakpoints[b],
+    ),
+    spacing,
+    spacingKeys: Object.keys(spacing).map((k) =>
+      isNaN(Number(k)) ? k : Number(k),
+    ),
+    output: userConfig.output ?? defaultConfig.output,
+  }
+}
+
+function generateCSS(config: ResolvedConfig): string {
+  const { breakpoints, breakpointKeys, spacingKeys, spacing } = config
+
+  let css = GENERATED_HEADER
+
+  css += `/* ----- Spacing Tokens ----- */\n`
+  css += `:root {\n`
+  for (const key of spacingKeys) {
+    css += `  --flex-spacing-${key}: ${spacing[key]};\n`
+  }
+  css += `}\n\n`
+
+  css += `[data-flex] {\n  display: flex;\n}\n\n`
+  css += `[data-flex][data-inline] {\n  display: inline-flex;\n}\n\n`
+
+  css += `/* ----- Axis ----- */\n`
+  for (const value of axis) {
+    css += `[data-flex][data-axis="${value}"] { flex-direction: ${axisToDirection[value]}; }\n`
+    css += `[data-flex][data-axis="${value}"][data-reverse] { flex-direction: ${axisToDirection[value]}-reverse; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Gap ----- */\n`
+  for (const key of spacingKeys) {
+    css += `[data-flex][data-gap="${key}"] { gap: var(--flex-spacing-${key}); }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Row Gap ----- */\n`
+  for (const key of spacingKeys) {
+    css += `[data-flex][data-row-gap="${key}"] { row-gap: var(--flex-spacing-${key}); }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Column Gap ----- */\n`
+  for (const key of spacingKeys) {
+    css += `[data-flex][data-column-gap="${key}"] { column-gap: var(--flex-spacing-${key}); }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Justify ----- */\n`
+  for (const value of justify) {
+    css += `[data-flex][data-justify="${value}"] { justify-content: ${justifyToCSS[value]}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Align ----- */\n`
+  for (const value of align) {
+    css += `[data-flex][data-align="${value}"] { align-items: ${alignToCSS[value]}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Align Content ----- */\n`
+  for (const value of alignContent) {
+    css += `[data-flex][data-align-content="${value}"] { align-content: ${alignContentToCSS[value]}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Wrap ----- */\n`
+  for (const value of wrap) {
+    css += `[data-flex][data-wrap="${value}"] { flex-wrap: ${value}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Flex Item: Grow ----- */\n`
+  for (let i = 0; i <= 5; i++) {
+    css += `[data-flex-item][data-grow="${i}"] { flex-grow: ${i}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Flex Item: Shrink ----- */\n`
+  for (let i = 0; i <= 3; i++) {
+    css += `[data-flex-item][data-shrink="${i}"] { flex-shrink: ${i}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Flex Item: Basis ----- */\n`
+  css += `[data-flex-item][data-basis="auto"] { flex-basis: auto; }\n`
+  css += `[data-flex-item][data-basis="0"] { flex-basis: 0; }\n`
+  css += `[data-flex-item][data-basis="full"] { flex-basis: 100%; }\n`
+  css += `[data-flex-item][data-basis="1/2"] { flex-basis: 50%; }\n`
+  css += `[data-flex-item][data-basis="1/3"] { flex-basis: 33.333333%; }\n`
+  css += `[data-flex-item][data-basis="2/3"] { flex-basis: 66.666667%; }\n`
+  css += `[data-flex-item][data-basis="1/4"] { flex-basis: 25%; }\n`
+  css += `[data-flex-item][data-basis="3/4"] { flex-basis: 75%; }\n`
+  css += `\n`
+
+  css += `/* ----- Flex Item: Align Self ----- */\n`
+  for (const value of alignSelf) {
+    css += `[data-flex-item][data-align-self="${value}"] { align-self: ${alignSelfToCSS[value]}; }\n`
+  }
+  css += `\n`
+
+  css += `/* ----- Flex Item: Order ----- */\n`
+  css += `[data-flex-item][data-order="first"] { order: -9999; }\n`
+  css += `[data-flex-item][data-order="last"] { order: 9999; }\n`
+  css += `[data-flex-item][data-order="none"] { order: 0; }\n`
+  for (let i = 1; i <= 12; i++) {
+    css += `[data-flex-item][data-order="${i}"] { order: ${i}; }\n`
+  }
+  css += `\n`
+
+  for (const bp of breakpointKeys) {
+    const minWidth = breakpoints[bp]
+    css += `/* ===== ${bp.toUpperCase()} (${minWidth}px) ===== */\n`
+    css += `@media screen and (min-width: ${minWidth}px) {\n`
+
+    for (const value of axis) {
+      css += `  [data-flex][data-axis-${bp}="${value}"] { flex-direction: ${axisToDirection[value]}; }\n`
+      css += `  [data-flex][data-axis-${bp}="${value}"][data-reverse] { flex-direction: ${axisToDirection[value]}-reverse; }\n`
+    }
+
+    for (const key of spacingKeys) {
+      css += `  [data-flex][data-gap-${bp}="${key}"] { gap: var(--flex-spacing-${key}); }\n`
+    }
+
+    for (const key of spacingKeys) {
+      css += `  [data-flex][data-row-gap-${bp}="${key}"] { row-gap: var(--flex-spacing-${key}); }\n`
+    }
+
+    for (const key of spacingKeys) {
+      css += `  [data-flex][data-column-gap-${bp}="${key}"] { column-gap: var(--flex-spacing-${key}); }\n`
+    }
+
+    for (const value of justify) {
+      css += `  [data-flex][data-justify-${bp}="${value}"] { justify-content: ${justifyToCSS[value]}; }\n`
+    }
+
+    for (const value of align) {
+      css += `  [data-flex][data-align-${bp}="${value}"] { align-items: ${alignToCSS[value]}; }\n`
+    }
+
+    for (const value of alignContent) {
+      css += `  [data-flex][data-align-content-${bp}="${value}"] { align-content: ${alignContentToCSS[value]}; }\n`
+    }
+
+    for (const value of wrap) {
+      css += `  [data-flex][data-wrap-${bp}="${value}"] { flex-wrap: ${value}; }\n`
+    }
+
+    for (let i = 0; i <= 5; i++) {
+      css += `  [data-flex-item][data-grow-${bp}="${i}"] { flex-grow: ${i}; }\n`
+    }
+
+    for (let i = 0; i <= 3; i++) {
+      css += `  [data-flex-item][data-shrink-${bp}="${i}"] { flex-shrink: ${i}; }\n`
+    }
+
+    css += `  [data-flex-item][data-basis-${bp}="auto"] { flex-basis: auto; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="0"] { flex-basis: 0; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="full"] { flex-basis: 100%; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="1/2"] { flex-basis: 50%; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="1/3"] { flex-basis: 33.333333%; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="2/3"] { flex-basis: 66.666667%; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="1/4"] { flex-basis: 25%; }\n`
+    css += `  [data-flex-item][data-basis-${bp}="3/4"] { flex-basis: 75%; }\n`
+
+    for (const value of alignSelf) {
+      css += `  [data-flex-item][data-align-self-${bp}="${value}"] { align-self: ${alignSelfToCSS[value]}; }\n`
+    }
+
+    css += `  [data-flex-item][data-order-${bp}="first"] { order: -9999; }\n`
+    css += `  [data-flex-item][data-order-${bp}="last"] { order: 9999; }\n`
+    css += `  [data-flex-item][data-order-${bp}="none"] { order: 0; }\n`
+    for (let i = 1; i <= 12; i++) {
+      css += `  [data-flex-item][data-order-${bp}="${i}"] { order: ${i}; }\n`
+    }
+
+    css += `}\n\n`
+  }
+
+  return css
+}
+
+function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * Main generation function
+ *
+ * @param cwd - Working directory for config file lookup and output
+ * @param inlineConfig - Optional config passed directly (skips file lookup)
+ */
+export async function generate(
+  cwd: string = process.cwd(),
+  inlineConfig?: FlexConfig,
+): Promise<void> {
+  console.log("🛠️  Generating CSS...\n")
+
+  const userConfig = inlineConfig ?? (await loadConfig(cwd))
+  const config = mergeConfig(userConfig)
+
+  const cssContent = generateCSS(config)
+  const cssPath = path.resolve(cwd, config.output)
+  ensureDir(cssPath)
+  fs.writeFileSync(cssPath, cssContent)
+  console.log(`✅ Saved to ${config.output}\n`)
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const isMain = process.argv[1] === __filename
+
+if (isMain) {
+  generate().catch((err) => {
+    console.error("Error:", err.message)
+    process.exit(1)
+  })
+}

package/src/config.ts

@@ -0,0 +1,115 @@
+/**
+ * Flex UI Configuration
+ *
+ * Consumers can create a flex.config.ts file to customize
+ * breakpoints, spacing, and output path for CSS generation.
+ */
+
+export interface SpacingConfig {
+  /**
+   * Base spacing unit (e.g., "4px", "0.25rem", "1rem")
+   * Each spacing step will be a multiple of this value
+   */
+  unit: string
+
+  /**
+   * Multipliers for each spacing step
+   * @example [0, 1, 2, 3, 4, 6, 8, 12, 16] generates 0, 4px, 8px, 12px, ...
+   */
+  scale: number[]
+}
+
+export interface FlexConfig {
+  /**
+   * Custom breakpoints (min-width in pixels)
+   * @example { sm: 640, md: 768, lg: 1024, xl: 1280 }
+   */
+  breakpoints?: Record<string, number>
+
+  /**
+   * Custom spacing - either explicit values or unit + multipliers
+   * @example { unit: '4px', scale: [0, 1, 2, 3, 4, 6, 8] }
+   * @example { 0: '0', 1: '0.25rem', 2: '0.5rem', 4: '1rem' }
+   */
+  spacing?: SpacingConfig | Record<string | number, string>
+
+  /**
+   * Output file path for generated CSS (relative to cwd)
+   * @default "./flex-ui.css"
+   */
+  output?: string
+}
+
+/**
+ * Check if spacing config uses unit + scale format
+ */
+export function isSpacingWithUnit(
+  spacing: SpacingConfig | Record<string | number, string>,
+): spacing is SpacingConfig {
+  return "unit" in spacing && "scale" in spacing
+}
+
+/**
+ * Resolve spacing config to final key-value pairs
+ */
+export function resolveSpacing(
+  spacing: SpacingConfig | Record<string | number, string>,
+): Record<string | number, string> {
+  if (!isSpacingWithUnit(spacing)) {
+    return spacing
+  }
+
+  const { unit, scale } = spacing
+  const unitMatch = unit.match(/^([\d.]+)(.+)$/)
+
+  if (!unitMatch) {
+    throw new Error(
+      `Invalid spacing unit: ${unit}. Expected format like "4px" or "0.25rem"`,
+    )
+  }
+
+  const unitValue = parseFloat(unitMatch[1])
+  const unitSuffix = unitMatch[2]
+
+  const resolved: Record<number, string> = {}
+  for (const multiplier of scale) {
+    const value = unitValue * multiplier
+    resolved[multiplier] = value === 0 ? "0" : `${value}${unitSuffix}`
+  }
+
+  return resolved
+}
+
+/**
+ * Default spacing using unit + scale format
+ */
+export const defaultSpacingConfig: SpacingConfig = {
+  unit: "8px",
+  scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+}
+
+/**
+ * Additional named spacing values
+ */
+export const namedSpacing: Record<string, string> = {
+  fourth: "2px",
+  half: "4px",
+}
+
+/**
+ * Default configuration values
+ */
+export const defaultConfig = {
+  breakpoints: {
+    xs: 480,
+    sm: 600,
+    md: 720,
+    lg: 960,
+    xl: 1200,
+  },
+  spacing: defaultSpacingConfig,
+  output: "./flex-ui.css",
+} as const satisfies Required<FlexConfig>
+
+export type DefaultBreakpoint = keyof typeof defaultConfig.breakpoints
+export type DefaultSpacing = (typeof defaultSpacingConfig.scale)[number]

package/src/tokens/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Design Tokens - Single Source of Truth
+ *
+ * All breakpoints, spacing values, and property options are defined here.
+ * Both the React component and CSS-only version are generated from these values.
+ */
+
+import {
+  defaultConfig,
+  defaultSpacingConfig,
+  namedSpacing,
+  resolveSpacing,
+} from "../config"
+
+// Breakpoints (min-width values in pixels)
+export const breakpoints = defaultConfig.breakpoints
+
+export type Breakpoint = keyof typeof breakpoints
+export const breakpointKeys = Object.keys(breakpoints) as Breakpoint[]
+
+// Spacing scale configuration
+export const spacingConfig = defaultSpacingConfig
+
+// Resolved spacing values (generated from unit + scale + named)
+export const spacing: Record<string | number, string> = {
+  ...resolveSpacing(spacingConfig),
+  ...namedSpacing,
+}
+
+export type SpacingValue =
+  | (typeof spacingConfig.scale)[number]
+  | keyof typeof namedSpacing
+export const spacingKeys: (string | number)[] = [
+  ...spacingConfig.scale,
+  ...Object.keys(namedSpacing),
+]
+
+// Axis values (maps to flex-direction)
+export const axis = ["horizontal", "vertical"] as const
+export type AxisValue = (typeof axis)[number]
+
+export const axisToDirection: Record<AxisValue, string> = {
+  horizontal: "row",
+  vertical: "column",
+}
+
+// Justify values (maps to justify-content)
+export const justify = [
+  "start",
+  "end",
+  "center",
+  "between",
+  "around",
+  "evenly",
+] as const
+export type JustifyValue = (typeof justify)[number]
+
+export const justifyToCSS: Record<JustifyValue, string> = {
+  start: "flex-start",
+  end: "flex-end",
+  center: "center",
+  between: "space-between",
+  around: "space-around",
+  evenly: "space-evenly",
+}
+
+// Align values (maps to align-items)
+export const align = ["start", "end", "center", "stretch", "baseline"] as const
+export type AlignValue = (typeof align)[number]
+
+export const alignToCSS: Record<AlignValue, string> = {
+  start: "flex-start",
+  end: "flex-end",
+  center: "center",
+  stretch: "stretch",
+  baseline: "baseline",
+}
+
+// Wrap values (maps to flex-wrap)
+export const wrap = ["nowrap", "wrap", "wrap-reverse"] as const
+export type WrapValue = (typeof wrap)[number]
+
+// Align Content values (for multi-line flex containers)
+export const alignContent = [
+  "start",
+  "end",
+  "center",
+  "stretch",
+  "between",
+  "around",
+  "evenly",
+] as const
+export type AlignContentValue = (typeof alignContent)[number]
+
+export const alignContentToCSS: Record<AlignContentValue, string> = {
+  start: "flex-start",
+  end: "flex-end",
+  center: "center",
+  stretch: "stretch",
+  between: "space-between",
+  around: "space-around",
+  evenly: "space-evenly",
+}
+
+// Flex item values for StackItem
+export const alignSelf = [
+  "auto",
+  "start",
+  "end",
+  "center",
+  "stretch",
+  "baseline",
+] as const
+export type AlignSelfValue = (typeof alignSelf)[number]
+
+export const alignSelfToCSS: Record<AlignSelfValue, string> = {
+  auto: "auto",
+  start: "flex-start",
+  end: "flex-end",
+  center: "center",
+  stretch: "stretch",
+  baseline: "baseline",
+}