create-bestax 2.2.0 → 3.1.0

package/templates/skills/bestax-form/references/patterns.md

@@ -0,0 +1,210 @@
+# Reference: form patterns
+
+## A complete multi-field form (controlled + manual validation)
+
+No form library — state is plain React, validation is a function, errors surface through
+`color` + `message` + `messageColor`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Input,
+  Select,
+  TextArea,
+  Checkbox,
+  Button,
+  Field,
+} from '@allxsmith/bestax-bulma';
+
+interface Values {
+  name: string;
+  email: string;
+  country: string;
+  bio: string;
+  agree: boolean;
+}
+
+function validate(v: Values) {
+  const errors: Partial<Record<keyof Values, string>> = {};
+  if (!v.name.trim()) errors.name = 'Name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v.email))
+    errors.email = 'Enter a valid email.';
+  if (!v.country) errors.country = 'Pick a country.';
+  if (!v.agree) errors.agree = 'You must accept the terms.';
+  return errors;
+}
+
+export function ProfileForm() {
+  const [values, setValues] = useState<Values>({
+    name: '',
+    email: '',
+    country: '',
+    bio: '',
+    agree: false,
+  });
+  const [submitted, setSubmitted] = useState(false);
+
+  const errors = validate(values);
+  const show = (k: keyof Values) => (submitted ? errors[k] : undefined);
+  const set = (k: keyof Values, val: Values[keyof Values]) =>
+    setValues(prev => ({ ...prev, [k]: val }));
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        setSubmitted(true);
+        if (Object.keys(errors).length === 0) {
+          // submit values…
+        }
+      }}
+    >
+      <Input
+        label="Name"
+        value={values.name}
+        onChange={e => set('name', e.target.value)}
+        color={show('name') ? 'danger' : undefined}
+        message={show('name')}
+        messageColor="danger"
+      />
+
+      <Input
+        label="Email"
+        type="email"
+        value={values.email}
+        onChange={e => set('email', e.target.value)}
+        color={show('email') ? 'danger' : undefined}
+        message={show('email')}
+        messageColor="danger"
+        iconLeftName="envelope"
+      />
+
+      <Select
+        label="Country"
+        value={values.country}
+        onChange={e => set('country', e.target.value)}
+        color={show('country') ? 'danger' : undefined}
+        message={show('country')}
+        messageColor="danger"
+      >
+        <option value="">Select…</option>
+        <option value="us">United States</option>
+        <option value="ca">Canada</option>
+      </Select>
+
+      <TextArea
+        label="Bio"
+        value={values.bio}
+        onChange={e => set('bio', e.target.value)}
+        rows={3}
+      />
+
+      <Field>
+        <Checkbox
+          checked={values.agree}
+          onChange={e => set('agree', e.target.checked)}
+        >
+          {' '}
+          I accept the terms
+        </Checkbox>
+        {show('agree') && <p className="help is-danger">{show('agree')}</p>}
+      </Field>
+
+      <Button color="primary" type="submit" mt="4">
+        Save
+      </Button>
+    </form>
+  );
+}
+```
+
+Notes:
+
+- Validation runs every render as a pure function; `submitted` gates when errors are shown so the
+  form isn't red before the user interacts. You could gate per-field on blur instead.
+- For the checkbox the convenience `message` prop isn't used; the help text is rendered manually
+  inside the `Field` — a good illustration of dropping to composition when needed.
+
+## Grouped controls and addons
+
+```tsx
+// Search box: input + button attached.
+<Field hasAddons>
+  <Control isExpanded>
+    <InputBase placeholder="Search" />
+  </Control>
+  <Control>
+    <Button color="primary">Search</Button>
+  </Control>
+</Field>
+
+// Two controls on one row.
+<Field grouped>
+  <Control>
+    <InputBase placeholder="First" />
+  </Control>
+  <Control>
+    <InputBase placeholder="Last" />
+  </Control>
+</Field>
+```
+
+## Horizontal field with explicit label/body
+
+```tsx
+<Field horizontal>
+  <Field.Label size="normal">Email</Field.Label>
+  <Field.Body>
+    <Control iconLeftName="envelope" hasIconsLeft>
+      <InputBase type="email" placeholder="you@example.com" />
+    </Control>
+  </Field.Body>
+</Field>
+```
+
+## Advanced inputs
+
+These are controlled the same way — own the value, pass `value`/`onChange`.
+
+```tsx
+// Autocomplete — onInput fires on typing, onSelect when a suggestion is chosen.
+const [city, setCity] = useState('');
+<Autocomplete
+  value={city}
+  onInput={setCity}
+  onSelect={item =>
+    setCity(typeof item === 'string' ? item : (item?.value ?? ''))
+  }
+  data={['Austin', 'Boston', 'Chicago']}
+  openOnFocus
+/>;
+
+// Slider (single and dual thumb)
+const [volume, setVolume] = useState(50);
+<Slider value={volume} onChange={setVolume} min={0} max={100} tooltip="auto" />;
+
+const [range, setRange] = useState<[number, number]>([20, 80]);
+<Slider range value={range} onChange={setRange} min={0} max={100} />;
+
+// Numberinput
+const [qty, setQty] = useState(1);
+<Numberinput value={qty} onChange={setQty} min={1} max={10} step={1} />;
+
+// Rate
+const [stars, setStars] = useState(3);
+<Rate value={stars} onChange={setStars} max={5} />;
+
+// Taginput — tags can be strings or { value, label } objects; onChange yields TaginputTag[].
+const [tags, setTags] = useState<string[]>(['react']);
+<Taginput
+  value={tags}
+  onChange={next =>
+    setTags(next.map(t => (typeof t === 'string' ? t : t.value)))
+  }
+  data={['react', 'bulma', 'ts']}
+/>;
+```
+
+Each renders inside Bulma's field/control structure already, so wrap them in a `Field` only when
+you need a label or grouped layout. Reflect validation on them with the same `color` /
+`message` / `messageColor` approach used for text inputs.

package/templates/skills/bestax-layout-scaffold/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: bestax-layout-scaffold
+description: Scaffold a complete, responsive page layout with @allxsmith/bestax-bulma — app shells/dashboards, marketing/landing pages, centered auth/settings pages, and card-grid catalogs. Use when building a full page or overall app layout (not a single component).
+license: MIT
+---
+
+# Scaffolding a page layout with @allxsmith/bestax-bulma
+
+Turn a high-level request ("admin dashboard", "landing page", "login screen", "product catalog")
+into a complete responsive page built from bestax-bulma layout components.
+
+## Behavioral rule
+
+Select an archetype from the request and build it in one shot. Do **not** ask layout questions
+("how many columns?", "where should the nav go?", "what width?") — infer the structure from the
+request and proceed. The archetype determines the structure; fill it with the requested content.
+
+Ask **at most one** clarifying question, and only for a high-level fork the request genuinely does
+not imply: whether the page is **public-facing** (marketing) or an **internal tool** (authenticated
+app). When the request already signals this ("dashboard", "admin", "landing", "login", "pricing"),
+skip the question and default.
+
+## Select an archetype
+
+| Request signals                                                        | Archetype     |
+| ---------------------------------------------------------------------- | ------------- |
+| dashboard, admin, console, internal tool, authenticated app, "sidebar" | **App shell** |
+| landing, marketing, homepage, product/pricing page, public site        | **Landing**   |
+| login, sign up, auth, settings, checkout, a single focused form        | **Centered**  |
+| catalog, gallery, products, listing, "grid of cards", search results   | **Card grid** |
+
+Default when ambiguous: internal tool → App shell; public-facing → Landing; one focused task →
+Centered; a collection of items → Card grid. For mixed requests, pick the dominant intent (e.g.
+"admin dashboard with a product list" → App shell whose main column holds a Card grid).
+
+## Approach
+
+- Compose pages from the shipped layout components — `Container`, `Section`, `Hero`, `Footer`,
+  `Level`, `Columns`/`Column`, `Navbar`, `Menu`, `Card`. There is **no `Tile` component** — build
+  grids with `Columns`/`Column`.
+- Rely on Bulma's responsive defaults: `Columns` sit side by side on tablet and up and stack on
+  mobile. Add responsive `size*` props only to tune the breakpoints.
+- For a `fixed="top"` `Navbar`, add the `has-navbar-fixed-top` class to `<html>` so content is not
+  hidden behind it — the library does not do this automatically.
+
+## References
+
+- `references/layout-components.md` — the layout component inventory: real prop names, types, and
+  accepted values, plus subcomponent nesting.
+- `references/archetypes.md` — the four archetypes: selection criteria, JSX skeleton, and responsive
+  behavior.
+
+## Examples
+
+- `examples/app-shell.tsx` — fixed `Navbar` + sidebar `Menu` + content (dashboard).
+- `examples/landing.tsx` — `Hero` + `Section`s + `Footer`.
+- `examples/centered.tsx` — centered single column (auth/settings).
+- `examples/card-grid.tsx` — multiline `Columns` of `Card`s (catalog).
+
+## Checklist
+
+- [ ] Map the request to one archetype; do not ask layout questions.
+- [ ] Wrap page content in `Container` (+ `Section` for vertical rhythm).
+- [ ] Use `Columns`/`Column` for side-by-side layout; rely on the mobile stack default.
+- [ ] For a fixed navbar, add `has-navbar-fixed-top` to `<html>`.
+- [ ] Do not use `Tile` — it is not shipped.

package/templates/skills/bestax-layout-scaffold/examples/app-shell.tsx

@@ -0,0 +1,80 @@
+// App shell with sidebar — fixed top Navbar + a narrow Menu column beside the
+// main content. The admin/dashboard default.
+//
+// A fixed-top navbar needs the `has-navbar-fixed-top` class on <html> so the page
+// is padded below it — Bulma requires this and the library does NOT add it for
+// you. The columns sit side by side on tablet and up, and stack (menu above
+// content) on mobile.
+import React, { useEffect, useState } from 'react';
+import {
+  Navbar,
+  Menu,
+  Container,
+  Columns,
+  Column,
+  Section,
+  Title,
+  Box,
+} from '@allxsmith/bestax-bulma';
+
+export default function AdminShell() {
+  const [menuOpen, setMenuOpen] = useState(false);
+
+  useEffect(() => {
+    document.documentElement.classList.add('has-navbar-fixed-top');
+    return () => {
+      document.documentElement.classList.remove('has-navbar-fixed-top');
+    };
+  }, []);
+
+  return (
+    <>
+      <Navbar fixed="top" color="dark">
+        <Navbar.Brand>
+          <Navbar.Item href="#">Acme Admin</Navbar.Item>
+          <Navbar.Burger
+            active={menuOpen}
+            onClick={() => setMenuOpen(open => !open)}
+            aria-label="menu"
+            aria-expanded={menuOpen}
+          />
+        </Navbar.Brand>
+        <Navbar.Menu active={menuOpen}>
+          <Navbar.End>
+            <Navbar.Item href="#">Docs</Navbar.Item>
+            <Navbar.Item href="#">Account</Navbar.Item>
+          </Navbar.End>
+        </Navbar.Menu>
+      </Navbar>
+
+      <Container fluid>
+        <Columns>
+          <Column size={3} sizeWidescreen={2}>
+            <Menu>
+              <Menu.Label>General</Menu.Label>
+              <Menu.List>
+                <Menu.Item active href="#">
+                  Dashboard
+                </Menu.Item>
+                <Menu.Item href="#">Customers</Menu.Item>
+                <Menu.Item href="#">Orders</Menu.Item>
+              </Menu.List>
+              <Menu.Label>Admin</Menu.Label>
+              <Menu.List>
+                <Menu.Item href="#">Team</Menu.Item>
+                <Menu.Item href="#">Settings</Menu.Item>
+              </Menu.List>
+            </Menu>
+          </Column>
+
+          <Column>
+            <Section>
+              <Title size="3">Dashboard</Title>
+              <Box>Main content area — drop dashboard widgets here.</Box>
+            </Section>
+          </Column>
+        </Columns>
+      </Container>
+    </>
+  );
+}

package/templates/skills/bestax-layout-scaffold/examples/card-grid.tsx

@@ -0,0 +1,98 @@
+// Card grid / catalog page — a collection of similar items.
+// `<Columns isMultiline>` wraps cards onto new rows; the responsive column sizes
+// give 1 card per row on mobile, 2 on tablet, 3 on desktop.
+import React from 'react';
+import {
+  Section,
+  Container,
+  Title,
+  Columns,
+  Column,
+  Card,
+} from '@allxsmith/bestax-bulma';
+
+interface Product {
+  id: number;
+  name: string;
+  price: string;
+  image: string;
+  blurb: string;
+}
+
+const PRODUCTS: Product[] = [
+  {
+    id: 1,
+    name: 'Aurora Lamp',
+    price: '$48',
+    image: 'https://picsum.photos/seed/1/600/400',
+    blurb: 'Warm ambient light.',
+  },
+  {
+    id: 2,
+    name: 'Drift Chair',
+    price: '$220',
+    image: 'https://picsum.photos/seed/2/600/400',
+    blurb: 'Ergonomic and airy.',
+  },
+  {
+    id: 3,
+    name: 'Stone Mug',
+    price: '$18',
+    image: 'https://picsum.photos/seed/3/600/400',
+    blurb: 'Hand-thrown ceramic.',
+  },
+  {
+    id: 4,
+    name: 'Field Notebook',
+    price: '$12',
+    image: 'https://picsum.photos/seed/4/600/400',
+    blurb: 'Pocket-sized, lined.',
+  },
+  {
+    id: 5,
+    name: 'Trail Bottle',
+    price: '$26',
+    image: 'https://picsum.photos/seed/5/600/400',
+    blurb: 'Insulated steel.',
+  },
+  {
+    id: 6,
+    name: 'Linen Throw',
+    price: '$64',
+    image: 'https://picsum.photos/seed/6/600/400',
+    blurb: 'Soft, breathable.',
+  },
+];
+
+export default function CatalogPage() {
+  return (
+    <Section>
+      <Container>
+        <Title size="3" mb="5">
+          Catalog
+        </Title>
+        <Columns isMultiline>
+          {PRODUCTS.map(product => (
+            <Column
+              key={product.id}
+              sizeMobile="full"
+              sizeTablet="half"
+              sizeDesktop="one-third"
+            >
+              <Card
+                image={product.image}
+                imageAlt={product.name}
+                header={product.name}
+                footer={
+                  <span className="card-footer-item">{product.price}</span>
+                }
+              >
+                <p>{product.blurb}</p>
+              </Card>
+            </Column>
+          ))}
+        </Columns>
+      </Container>
+    </Section>
+  );
+}

package/templates/skills/bestax-layout-scaffold/examples/centered.tsx

@@ -0,0 +1,56 @@
+// Centered single-column page — auth, settings, focused forms.
+// A narrow column is centered with `<Columns isCentered>`; on mobile the column
+// becomes full width automatically.
+import React from 'react';
+import {
+  Section,
+  Container,
+  Columns,
+  Column,
+  Box,
+  Title,
+  SubTitle,
+  Input,
+  Button,
+} from '@allxsmith/bestax-bulma';
+
+export default function LoginPage() {
+  return (
+    <Section>
+      <Container>
+        <Columns isCentered>
+          <Column
+            size="half"
+            sizeTablet="two-thirds"
+            sizeDesktop="half"
+            sizeWidescreen="one-third"
+          >
+            <Box>
+              <Title size="4" textAlign="centered">
+                Sign in
+              </Title>
+              <SubTitle size="6" textAlign="centered" textColor="grey">
+                Welcome back
+              </SubTitle>
+              <Input
+                label="Email"
+                type="email"
+                iconLeftName="envelope"
+                placeholder="you@example.com"
+              />
+              <Input
+                label="Password"
+                type="password"
+                iconLeftName="lock"
+                placeholder="••••••••"
+              />
+              <Button color="primary" isFullWidth mt="4">
+                Sign in
+              </Button>
+            </Box>
+          </Column>
+        </Columns>
+      </Container>
+    </Section>
+  );
+}

package/templates/skills/bestax-layout-scaffold/examples/landing.tsx

@@ -0,0 +1,77 @@
+// Marketing / landing page — Hero + stacked Sections + Footer.
+// Each Section stacks vertically; the feature Columns collapse to one per row on
+// mobile (Bulma columns stack below the tablet breakpoint).
+import React from 'react';
+import {
+  Hero,
+  Section,
+  Container,
+  Footer,
+  Columns,
+  Column,
+  Box,
+  Title,
+  SubTitle,
+  Content,
+  Button,
+  Buttons,
+} from '@allxsmith/bestax-bulma';
+
+const FEATURES = [
+  { title: 'Fast', body: 'Ship pages in minutes, not days.' },
+  { title: 'Responsive', body: 'Looks right on every screen by default.' },
+  { title: 'Composable', body: 'Build from small, predictable pieces.' },
+];
+
+export default function LandingPage() {
+  return (
+    <>
+      <Hero color="primary" size="medium">
+        <Hero.Body>
+          <Container textAlign="centered">
+            <Title size="1">Ship faster with Acme</Title>
+            <SubTitle size="3">
+              The all-in-one platform for modern teams.
+            </SubTitle>
+            <Buttons isCentered mt="5">
+              <Button color="light" size="large">
+                Get started
+              </Button>
+              <Button color="primary" isInverted isOutlined size="large">
+                Live demo
+              </Button>
+            </Buttons>
+          </Container>
+        </Hero.Body>
+      </Hero>
+
+      <Section size="large">
+        <Container>
+          <Title size="3" textAlign="centered" mb="6">
+            Why Acme
+          </Title>
+          <Columns>
+            {FEATURES.map(feature => (
+              <Column key={feature.title}>
+                <Box>
+                  <Title size="5">{feature.title}</Title>
+                  <Content>{feature.body}</Content>
+                </Box>
+              </Column>
+            ))}
+          </Columns>
+        </Container>
+      </Section>
+
+      <Footer>
+        <Container>
+          <Content textAlign="centered">
+            <p>
+              <strong>Acme</strong> — built with bestax-bulma.
+            </p>
+          </Content>
+        </Container>
+      </Footer>
+    </>
+  );
+}