@openwarelabs/blocks 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# Openware UI blocks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Whole page sections built from [Openware UI](https://github.com/openwarelabs/ui) (`@openwarelabs/ui`), as React components that take their content as props. Drop one in, pass your words, actions and screenshots, and it follows the theme, the brand colour and every screen width.
+
+```sh
+npm install @openwarelabs/ui @openwarelabs/blocks
+```
+
+```tsx
+import "@openwarelabs/ui/fonts.css";
+import "@openwarelabs/ui/styles.css";
+import "@openwarelabs/blocks/styles.css"; // after the library's
+
+import { Hero01 } from "@openwarelabs/blocks";
+
+<Hero01
+    eyebrow="New: agents that open their own pull requests"
+    title="The workspace for shipping software"
+    description="Plan the work, hand the routine parts to agents, review every change and ship it."
+    primaryAction={{ label: "Start for free", href: "/signup" }}
+    secondaryAction={{ label: "Book a demo", href: "/demo" }}
+    note="Free for teams of up to five. No card needed."
+    visual={<img src="/screenshot.png" alt="The overview page" />}
+/>;
+```
+
+The page needs `data-theme` on `<html>` and `class="ow-app"` on `<body>`, as for the library.
+
+## Blocks
+
+| Component | What it is                                                     | Content                                                                                                |
+| --------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Hero01`  | Centred, with a screenshot below that runs on into the page    | `title`, `description`, `primaryAction`, `secondaryAction`, `eyebrow`, `note`, `visual`                |
+| `Hero02`  | Split: words on the left, the product on the right             | the same, plus `points` (ticked reasons to believe)                                                    |
+| `Hero03`  | With an email field, for a waitlist or a trial                 | `submitLabel`, `onSubmit(email)`, `successTitle`, `successDescription`, `labels` for the field's words |
+| `Hero04`  | On Openware's dot grid, with room either side                  | `start`, `end`, `interactive`                                                                          |
+| `Hero05`  | With customers' logos below                                    | `logosTitle`, `logos: { name, logo }[]`                                                                |
+| `Hero06`  | Download buttons for a desktop app, the visitor's system first | `platforms: { id, name, requirement, href \| onDownload }[]`, `version`, `otherDownloads`              |
+
+Actions are `{ label, href?, onClick?, startIcon?, endIcon? }`: with `href` they're links styled as buttons, so they work with any router. Every block also takes the attributes of its `<section>` (`className`, `id` and so on). The docs show each one live, with its props: `npm run dev` in the repository, then Blocks → Heroes.
+
+More blocks become components release by release; until then, the others in the docs are code to copy.
+
+## With AI tools
+
+The Openware MCP server (`npx -y @openwarelabs/ui-mcp`) knows every block's props and examples, so Claude Code, Codex or Cursor use the components rather than rewriting them.

package/dist/heroes/Hero01/Hero01.d.cts

@@ -0,0 +1,3 @@
+import type { Hero01Props } from "./Hero01.types.cjs";
+/** A centred hero: an eyebrow, the headline, a lead, two actions and a note, with the product below, running on into the page. */
+export declare function Hero01({ eyebrow, title, description, primaryAction, secondaryAction, note, visual, className, ...props }: Hero01Props): import("react").JSX.Element;

package/dist/heroes/Hero01/Hero01.d.ts

@@ -0,0 +1,3 @@
+import type { Hero01Props } from "./Hero01.types.js";
+/** A centred hero: an eyebrow, the headline, a lead, two actions and a note, with the product below, running on into the page. */
+export declare function Hero01({ eyebrow, title, description, primaryAction, secondaryAction, note, visual, className, ...props }: Hero01Props): import("react").JSX.Element;

package/dist/heroes/Hero01/Hero01.types.d.cts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.cjs";
+export interface Hero01Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title: news, a launch or the product's name. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style: what the product does, in a few words. */
+    title: ReactNode;
+    /** A sentence or two under the title: who it's for and what it changes. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second, lower-stakes action beside it. */
+    secondaryAction?: BlockAction;
+    /** A small line under the buttons, such as "Free for teams of up to five. No card needed." */
+    note?: ReactNode;
+    /** The product under the text, usually a screenshot (`<img src alt>`). It's centred, up to 1080px wide, and fades out at the bottom. */
+    visual?: ReactNode;
+}

package/dist/heroes/Hero01/Hero01.types.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.js";
+export interface Hero01Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title: news, a launch or the product's name. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style: what the product does, in a few words. */
+    title: ReactNode;
+    /** A sentence or two under the title: who it's for and what it changes. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second, lower-stakes action beside it. */
+    secondaryAction?: BlockAction;
+    /** A small line under the buttons, such as "Free for teams of up to five. No card needed." */
+    note?: ReactNode;
+    /** The product under the text, usually a screenshot (`<img src alt>`). It's centred, up to 1080px wide, and fades out at the bottom. */
+    visual?: ReactNode;
+}

package/dist/heroes/Hero02/Hero02.d.cts

@@ -0,0 +1,3 @@
+import type { Hero02Props } from "./Hero02.types.cjs";
+/** A split hero: the words on the left and the product on the right. They stack on phones. */
+export declare function Hero02({ eyebrow, title, description, primaryAction, secondaryAction, points, visual, className, ...props }: Hero02Props): import("react").JSX.Element;

package/dist/heroes/Hero02/Hero02.d.ts

@@ -0,0 +1,3 @@
+import type { Hero02Props } from "./Hero02.types.js";
+/** A split hero: the words on the left and the product on the right. They stack on phones. */
+export declare function Hero02({ eyebrow, title, description, primaryAction, secondaryAction, points, visual, className, ...props }: Hero02Props): import("react").JSX.Element;

package/dist/heroes/Hero02/Hero02.types.d.cts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.cjs";
+export interface Hero02Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline. In half the width it takes the page-title size, so a few words fit on a line. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it, such as a demo. */
+    secondaryAction?: BlockAction;
+    /** Short reasons to believe it, each with a tick: "Runs in your own CI". */
+    points?: ReactNode[];
+    /** The product on the right (under the text on phones), usually a screenshot. */
+    visual?: ReactNode;
+}

package/dist/heroes/Hero02/Hero02.types.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.js";
+export interface Hero02Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline. In half the width it takes the page-title size, so a few words fit on a line. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it, such as a demo. */
+    secondaryAction?: BlockAction;
+    /** Short reasons to believe it, each with a tick: "Runs in your own CI". */
+    points?: ReactNode[];
+    /** The product on the right (under the text on phones), usually a screenshot. */
+    visual?: ReactNode;
+}

package/dist/heroes/Hero03/Hero03.d.cts

@@ -0,0 +1,3 @@
+import type { Hero03Props } from "./Hero03.types.cjs";
+/** A hero with an email field: join a waitlist or start a trial in one step, with a confirmation in place of the form. */
+export declare function Hero03({ eyebrow, title, description, submitLabel, onSubmit, note, successTitle, successDescription, visual, labels, className, ...props }: Hero03Props): import("react").JSX.Element;

package/dist/heroes/Hero03/Hero03.d.ts

@@ -0,0 +1,3 @@
+import type { Hero03Props } from "./Hero03.types.js";
+/** A hero with an email field: join a waitlist or start a trial in one step, with a confirmation in place of the form. */
+export declare function Hero03({ eyebrow, title, description, submitLabel, onSubmit, note, successTitle, successDescription, visual, labels, className, ...props }: Hero03Props): import("react").JSX.Element;

package/dist/heroes/Hero03/Hero03.types.d.cts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/** The words around the form that aren't content, in English unless you pass your own. */
+export interface Hero03Labels {
+    /** The field's accessible name. @default "Work email" */
+    email?: string;
+    /** @default "you@company.com" */
+    placeholder?: string;
+    /** The button that brings the form back after joining. @default "Change email" */
+    change?: string;
+    /** @default "Enter your work email to join the waitlist." */
+    empty?: string;
+    /** @default "That doesn't look like an email address. Try one like maya@example.com." */
+    invalid?: string;
+    /** Shown when `onSubmit` fails without a message of its own. @default "That didn't go through. Try again in a moment." */
+    failed?: string;
+}
+export interface Hero03Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children" | "onSubmit"> {
+    /** A short line in a Chip above the title, such as "Early access". */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The button's words: "Join the waitlist", "Start your trial". */
+    submitLabel: ReactNode;
+    /**
+     * Sends the address to your waitlist. While its promise is pending the button shows a spinner; if it throws,
+     * the error's message shows under the field, and once it resolves the form gives way to `successTitle`.
+     */
+    onSubmit(email: string): void | Promise<void>;
+    /** A small line under the field, such as "One email when your place is ready. Nothing else." */
+    note?: ReactNode;
+    /** What replaces the form once someone has joined: "You're on the list". */
+    successTitle: ReactNode;
+    /** A line under it, given the address they joined with. */
+    successDescription?(email: string): ReactNode;
+    /** Something under the form: a screenshot, or what they'll get. */
+    visual?: ReactNode;
+    labels?: Hero03Labels;
+}

package/dist/heroes/Hero03/Hero03.types.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/** The words around the form that aren't content, in English unless you pass your own. */
+export interface Hero03Labels {
+    /** The field's accessible name. @default "Work email" */
+    email?: string;
+    /** @default "you@company.com" */
+    placeholder?: string;
+    /** The button that brings the form back after joining. @default "Change email" */
+    change?: string;
+    /** @default "Enter your work email to join the waitlist." */
+    empty?: string;
+    /** @default "That doesn't look like an email address. Try one like maya@example.com." */
+    invalid?: string;
+    /** Shown when `onSubmit` fails without a message of its own. @default "That didn't go through. Try again in a moment." */
+    failed?: string;
+}
+export interface Hero03Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children" | "onSubmit"> {
+    /** A short line in a Chip above the title, such as "Early access". */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The button's words: "Join the waitlist", "Start your trial". */
+    submitLabel: ReactNode;
+    /**
+     * Sends the address to your waitlist. While its promise is pending the button shows a spinner; if it throws,
+     * the error's message shows under the field, and once it resolves the form gives way to `successTitle`.
+     */
+    onSubmit(email: string): void | Promise<void>;
+    /** A small line under the field, such as "One email when your place is ready. Nothing else." */
+    note?: ReactNode;
+    /** What replaces the form once someone has joined: "You're on the list". */
+    successTitle: ReactNode;
+    /** A line under it, given the address they joined with. */
+    successDescription?(email: string): ReactNode;
+    /** Something under the form: a screenshot, or what they'll get. */
+    visual?: ReactNode;
+    labels?: Hero03Labels;
+}

package/dist/heroes/Hero04/Hero04.d.cts

@@ -0,0 +1,3 @@
+import type { Hero04Props } from "./Hero04.types.cjs";
+/** A hero on Openware's dot grid, with the dots turning brass under the pointer and room for something either side. */
+export declare function Hero04({ eyebrow, title, description, primaryAction, secondaryAction, start, end, interactive, className, ...props }: Hero04Props): import("react").JSX.Element;

package/dist/heroes/Hero04/Hero04.d.ts

@@ -0,0 +1,3 @@
+import type { Hero04Props } from "./Hero04.types.js";
+/** A hero on Openware's dot grid, with the dots turning brass under the pointer and room for something either side. */
+export declare function Hero04({ eyebrow, title, description, primaryAction, secondaryAction, start, end, interactive, className, ...props }: Hero04Props): import("react").JSX.Element;

package/dist/heroes/Hero04/Hero04.types.d.cts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.cjs";
+export interface Hero04Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it. */
+    secondaryAction?: BlockAction;
+    /** Something beside the text on the left, such as a few cards. Hidden below 1180px wide, where there's no room. */
+    start?: ReactNode;
+    /** The same on the right. */
+    end?: ReactNode;
+    /** The dots turn brass under the pointer.
+     * @default true */
+    interactive?: boolean;
+}

package/dist/heroes/Hero04/Hero04.types.d.ts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.js";
+export interface Hero04Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it. */
+    secondaryAction?: BlockAction;
+    /** Something beside the text on the left, such as a few cards. Hidden below 1180px wide, where there's no room. */
+    start?: ReactNode;
+    /** The same on the right. */
+    end?: ReactNode;
+    /** The dots turn brass under the pointer.
+     * @default true */
+    interactive?: boolean;
+}

package/dist/heroes/Hero05/Hero05.d.cts

@@ -0,0 +1,3 @@
+import type { Hero05Props } from "./Hero05.types.cjs";
+/** The usual hero, with the headline beside the lead, then a row of customers' logos as the first proof. */
+export declare function Hero05({ eyebrow, title, description, primaryAction, secondaryAction, logosTitle, logos, className, ...props }: Hero05Props): import("react").JSX.Element;

package/dist/heroes/Hero05/Hero05.d.ts

@@ -0,0 +1,3 @@
+import type { Hero05Props } from "./Hero05.types.js";
+/** The usual hero, with the headline beside the lead, then a row of customers' logos as the first proof. */
+export declare function Hero05({ eyebrow, title, description, primaryAction, secondaryAction, logosTitle, logos, className, ...props }: Hero05Props): import("react").JSX.Element;

package/dist/heroes/Hero05/Hero05.types.d.cts

@@ -0,0 +1,24 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.cjs";
+export interface Hero05Logo {
+    /** The company, for the list's key. Put it in the logo too: as the <img>'s alt, or as text beside an SVG. */
+    name: string;
+    /** The logo: an `<img src alt>` or an inline SVG, in one colour (currentColor), about 22px tall. */
+    logo: ReactNode;
+}
+export interface Hero05Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style, on the left. */
+    title: ReactNode;
+    /** A sentence or two, on the right beside the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it. */
+    secondaryAction?: BlockAction;
+    /** A line above the logos: "These teams ship with Acme every day". */
+    logosTitle: ReactNode;
+    /** Customers' logos, in a row that wraps to a grid on smaller screens. Six to eight look best. */
+    logos: Hero05Logo[];
+}

package/dist/heroes/Hero05/Hero05.types.d.ts

@@ -0,0 +1,24 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockAction } from "../../shared/shared.types.js";
+export interface Hero05Logo {
+    /** The company, for the list's key. Put it in the logo too: as the <img>'s alt, or as text beside an SVG. */
+    name: string;
+    /** The logo: an `<img src alt>` or an inline SVG, in one colour (currentColor), about 22px tall. */
+    logo: ReactNode;
+}
+export interface Hero05Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title. */
+    eyebrow?: ReactNode;
+    /** The headline, in the hero style, on the left. */
+    title: ReactNode;
+    /** A sentence or two, on the right beside the title. */
+    description: ReactNode;
+    /** The one main action, as a primary pill button. */
+    primaryAction: BlockAction;
+    /** A second action beside it. */
+    secondaryAction?: BlockAction;
+    /** A line above the logos: "These teams ship with Acme every day". */
+    logosTitle: ReactNode;
+    /** Customers' logos, in a row that wraps to a grid on smaller screens. Six to eight look best. */
+    logos: Hero05Logo[];
+}

package/dist/heroes/Hero06/Hero06.d.cts

@@ -0,0 +1,3 @@
+import type { Hero06Props } from "./Hero06.types.cjs";
+/** A hero for a desktop app: a download button for each system, with the visitor's own first, and the app beside it. */
+export declare function Hero06({ eyebrow, title, description, platforms, version, otherDownloads, downloadLabel, visual, className, ...props }: Hero06Props): import("react").JSX.Element;

package/dist/heroes/Hero06/Hero06.d.ts

@@ -0,0 +1,3 @@
+import type { Hero06Props } from "./Hero06.types.js";
+/** A hero for a desktop app: a download button for each system, with the visitor's own first, and the app beside it. */
+export declare function Hero06({ eyebrow, title, description, platforms, version, otherDownloads, downloadLabel, visual, className, ...props }: Hero06Props): import("react").JSX.Element;

package/dist/heroes/Hero06/Hero06.types.d.cts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockLink } from "../../shared/shared.types.cjs";
+/** The systems Hero06 can recognise, to put the visitor's own first. */
+export type Hero06PlatformId = "mac" | "windows" | "linux";
+export interface Hero06Platform {
+    id: Hero06PlatformId;
+    /** "macOS", "Windows", "Linux". */
+    name: string;
+    /** What it needs, shown for the visitor's system: "macOS 13 or later". */
+    requirement?: ReactNode;
+    /** The download's address. Makes the button a link. */
+    href?: string;
+    /** Runs when its button is pressed, for a download you start yourself. */
+    onDownload?(): void;
+}
+export interface Hero06Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title, such as "Acme for desktop". */
+    eyebrow?: ReactNode;
+    /** The headline. In half the width it takes the page-title size. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /**
+     * A button for each system. The visitor's own (or the first, on phones and anything unknown) leads as the primary
+     * "Download for …" button; the rest follow as smaller ones with just their names.
+     */
+    platforms: Hero06Platform[];
+    /** Shown under the buttons, before the requirement: "Version 3.2.0". */
+    version?: ReactNode;
+    /** A link at the end of that line, to every download. */
+    otherDownloads?: BlockLink;
+    /** The primary button's words.
+     * @default (name) => `Download for ${name}` */
+    downloadLabel?(name: string): string;
+    /** The app on the right (under the text on phones), usually a screenshot. */
+    visual?: ReactNode;
+}

package/dist/heroes/Hero06/Hero06.types.d.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { BlockLink } from "../../shared/shared.types.js";
+/** The systems Hero06 can recognise, to put the visitor's own first. */
+export type Hero06PlatformId = "mac" | "windows" | "linux";
+export interface Hero06Platform {
+    id: Hero06PlatformId;
+    /** "macOS", "Windows", "Linux". */
+    name: string;
+    /** What it needs, shown for the visitor's system: "macOS 13 or later". */
+    requirement?: ReactNode;
+    /** The download's address. Makes the button a link. */
+    href?: string;
+    /** Runs when its button is pressed, for a download you start yourself. */
+    onDownload?(): void;
+}
+export interface Hero06Props extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** A short line in a Chip above the title, such as "Acme for desktop". */
+    eyebrow?: ReactNode;
+    /** The headline. In half the width it takes the page-title size. */
+    title: ReactNode;
+    /** A sentence or two under the title. */
+    description: ReactNode;
+    /**
+     * A button for each system. The visitor's own (or the first, on phones and anything unknown) leads as the primary
+     * "Download for …" button; the rest follow as smaller ones with just their names.
+     */
+    platforms: Hero06Platform[];
+    /** Shown under the buttons, before the requirement: "Version 3.2.0". */
+    version?: ReactNode;
+    /** A link at the end of that line, to every download. */
+    otherDownloads?: BlockLink;
+    /** The primary button's words.
+     * @default (name) => `Download for ${name}` */
+    downloadLabel?(name: string): string;
+    /** The app on the right (under the text on phones), usually a screenshot. */
+    visual?: ReactNode;
+}