@joshwilkerson/flex-ui 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,141 @@
+# flex-ui
+
+CSS-first responsive flexbox layouts using data attributes. Works with plain HTML or as React components.
+
+## Install
+
+```bash
+npm install flex-ui
+```
+
+## CSS-Only Usage
+
+Include the CSS and use data attributes directly on your HTML:
+
+```html
+<link rel="stylesheet" href="node_modules/flex-ui/dist/flex-ui.css" />
+
+<div data-flex data-axis="horizontal" data-gap="2" data-align="center">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### Flex Container
+
+Add the `data-flex` attribute and configure with data attributes:
+
+| Attribute | Values | Description |
+|---|---|---|
+| `data-axis` | `horizontal`, `vertical` | Flex direction |
+| `data-gap` | `0`-`10`, `half`, `fourth` | Gap between items |
+| `data-row-gap` | `0`-`10`, `half`, `fourth` | Row gap |
+| `data-column-gap` | `0`-`10`, `half`, `fourth` | Column gap |
+| `data-justify` | `start`, `end`, `center`, `between`, `around`, `evenly` | Main axis alignment |
+| `data-align` | `start`, `end`, `center`, `stretch`, `baseline` | Cross axis alignment |
+| `data-align-content` | `start`, `end`, `center`, `stretch`, `between`, `around`, `evenly` | Multi-line alignment |
+| `data-wrap` | `nowrap`, `wrap`, `wrap-reverse` | Wrap behavior |
+| `data-reverse` | (boolean) | Reverse direction |
+| `data-inline` | (boolean) | Use `inline-flex` |
+
+### Flex Item
+
+Add the `data-flex-item` attribute to children for additional control:
+
+| Attribute | Values | Description |
+|---|---|---|
+| `data-grow` | `0`-`5` | Flex grow |
+| `data-shrink` | `0`-`3` | Flex shrink |
+| `data-basis` | `auto`, `0`, `full`, `1/2`, `1/3`, `2/3`, `1/4`, `3/4` | Flex basis |
+| `data-align-self` | `auto`, `start`, `end`, `center`, `stretch`, `baseline` | Override container alignment |
+| `data-order` | `1`-`12`, `first`, `last`, `none` | Visual order |
+
+### Responsive
+
+Append a breakpoint suffix to any attribute for responsive behavior:
+
+```html
+<!-- Vertical on mobile, horizontal from md up -->
+<div data-flex data-axis="vertical" data-axis-md="horizontal" data-gap="1" data-gap-lg="3">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+Breakpoints: `xs` (480px), `sm` (600px), `md` (720px), `lg` (960px), `xl` (1200px)
+
+## React Components
+
+Optional React wrapper that outputs the same data attributes:
+
+```tsx
+import { Flex, FlexItem } from "flex-ui/react"
+import "flex-ui" // include the CSS
+
+<Flex axis="horizontal" gap={2} align="center">
+  <FlexItem grow={1}>Main</FlexItem>
+  <FlexItem basis="1/4">Sidebar</FlexItem>
+</Flex>
+```
+
+Props accept responsive objects:
+
+```tsx
+<Flex
+  axis={{ base: "vertical", md: "horizontal" }}
+  gap={{ base: 1, lg: 3 }}
+>
+  <FlexItem basis={{ base: "full", md: "1/2" }}>Half</FlexItem>
+  <FlexItem basis={{ base: "full", md: "1/2" }}>Half</FlexItem>
+</Flex>
+```
+
+## Spacing Scale
+
+The default spacing scale uses an 8px base unit:
+
+| Key | Value |
+|---|---|
+| `0` | 0 |
+| `fourth` | 2px |
+| `half` | 4px |
+| `1` | 8px |
+| `2` | 16px |
+| `3` | 24px |
+| `4` | 32px |
+| `5` | 40px |
+| `6` | 48px |
+| `7` | 56px |
+| `8` | 64px |
+| `9` | 72px |
+| `10` | 80px |
+
+Override spacing at runtime with CSS custom properties:
+
+```css
+:root {
+  --flex-spacing-2: 1rem;
+  --flex-spacing-half: 0.125rem;
+}
+```
+
+## Customization
+
+Generate a custom CSS file with your own breakpoints and spacing:
+
+```bash
+npx flex-ui
+```
+
+The interactive CLI walks you through:
+
+1. Adjusting breakpoint values (xs, sm, md, lg, xl)
+2. Setting a base spacing unit (e.g., `4px`, `0.5rem`)
+3. Choosing an output path
+
+The generated CSS replaces the default `flex-ui.css` with your custom values.
+
+## License
+
+MIT

package/bin/flex-ui.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env npx tsx
+/**
+ * Flex UI CLI
+ *
+ * Usage:
+ *   npx flex-ui        Interactive customization + CSS generation
+ *   npx flex-ui --help Show help
+ */
+
+import "../scripts/cli.js"

package/dist/config.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function c(t){return"unit"in t&&"scale"in t}function f(t){if(!c(t))return t;const{unit:i,scale:r}=t,n=i.match(/^([\d.]+)(.+)$/);if(!n)throw new Error(`Invalid spacing unit: ${i}. Expected format like "4px" or "0.25rem"`);const s=parseFloat(n[1]),l=n[2],e={};for(const o of r){const a=s*o;e[o]=a===0?"0":`${a}${l}`}return e}const u={unit:"8px",scale:[0,1,2,3,4,5,6,7,8,9,10]},p={fourth:"2px",half:"4px"},g={breakpoints:{xs:480,sm:600,md:720,lg:960,xl:1200},spacing:u,output:"./flex-ui.css"};exports.defaultConfig=g;exports.defaultSpacingConfig=u;exports.isSpacingWithUnit=c;exports.namedSpacing=p;exports.resolveSpacing=f;

package/dist/config.d.ts

@@ -0,0 +1,78 @@
+export declare type DefaultBreakpoint = keyof typeof defaultConfig.breakpoints;
+
+/**
+ * Default configuration values
+ */
+export declare const defaultConfig: {
+    readonly breakpoints: {
+        readonly xs: 480;
+        readonly sm: 600;
+        readonly md: 720;
+        readonly lg: 960;
+        readonly xl: 1200;
+    };
+    readonly spacing: SpacingConfig;
+    readonly output: "./flex-ui.css";
+};
+
+export declare type DefaultSpacing = (typeof defaultSpacingConfig.scale)[number];
+
+/**
+ * Default spacing using unit + scale format
+ */
+export declare const defaultSpacingConfig: SpacingConfig;
+
+export declare 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 declare function isSpacingWithUnit(spacing: SpacingConfig | Record<string | number, string>): spacing is SpacingConfig;
+
+/**
+ * Additional named spacing values
+ */
+export declare const namedSpacing: Record<string, string>;
+
+/**
+ * Resolve spacing config to final key-value pairs
+ */
+export declare function resolveSpacing(spacing: SpacingConfig | Record<string | number, string>): Record<string | number, string>;
+
+/**
+ * Flex UI Configuration
+ *
+ * Consumers can create a flex.config.ts file to customize
+ * breakpoints, spacing, and output path for CSS generation.
+ */
+export declare 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 { }

package/dist/config.js

@@ -0,0 +1,42 @@
+function a(t) {
+  return "unit" in t && "scale" in t;
+}
+function f(t) {
+  if (!a(t))
+    return t;
+  const { unit: i, scale: u } = t, n = i.match(/^([\d.]+)(.+)$/);
+  if (!n)
+    throw new Error(
+      `Invalid spacing unit: ${i}. Expected format like "4px" or "0.25rem"`
+    );
+  const r = parseFloat(n[1]), s = n[2], o = {};
+  for (const e of u) {
+    const c = r * e;
+    o[e] = c === 0 ? "0" : `${c}${s}`;
+  }
+  return o;
+}
+const l = {
+  unit: "8px",
+  scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+}, p = {
+  fourth: "2px",
+  half: "4px"
+}, x = {
+  breakpoints: {
+    xs: 480,
+    sm: 600,
+    md: 720,
+    lg: 960,
+    xl: 1200
+  },
+  spacing: l,
+  output: "./flex-ui.css"
+};
+export {
+  x as defaultConfig,
+  l as defaultSpacingConfig,
+  a as isSpacingWithUnit,
+  p as namedSpacing,
+  f as resolveSpacing
+};