boreal-ui 0.0.888 → 0.0.890

package/README.md

@@ -4,12 +4,14 @@ Boreal UI is a customizable, accessible React and Next.js component library with
 
 Use it when you want production-ready UI primitives that can be themed globally, customized per component, tested predictably, and imported in either standard React apps or Next.js app-router projects.
 
+[View the Boreal UI docs](https://www.borealui.ca)
+
 ## Highlights
 
 - **React and Next.js builds:** import from `boreal-ui/core` for React apps or `boreal-ui/next` for Next.js apps.
 - **Deep component set:** buttons, forms, navigation, data display, feedback, overlays, layout primitives, and utility components.
 - **Theme system:** curated color schemes, custom schemes, runtime theme selection, CSS variables, and `ThemeSelect`.
-- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig` or `setBorealStyleConfig`.
+- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig` or `setBorealStyleConfig`.
 - **Accessible by default:** semantic markup, ARIA support, keyboard behavior, visible focus states, disabled states, live announcements where useful, and predictable test IDs.
 - **Styling flexibility:** theme, state, size, rounding, shadow, outline, glass, custom class names, SCSS variables, and consumer CSS overrides.
 - **Typed public API:** TypeScript component props, shared type exports, and generated prop documentation objects for docs tooling.
@@ -17,30 +19,31 @@ Use it when you want production-ready UI primitives that can be themed globally,
 
 ## Installation
 
-```bash
-npm install boreal-ui
-```
-
-Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed. `marked` and `uuid` are peer dependencies because some components and utilities rely on them.
-
-## CLI Setup
-
-Use the CLI inside an existing React or Next.js project to add only the file changes Boreal UI needs: the package dependency, the global stylesheet import, `ThemeProvider`, and default style config.
-
-```bash
-npx boreal-ui@latest init
-```
-
-You can preview changes or run non-interactively:
-
-```bash
-npx boreal-ui init --dry-run
-npx boreal-ui init --framework next --yes
-```
-
-## Setup
-
-Import the global stylesheet once near the top of your application.
+```bash
+npm install boreal-ui
+```
+
+Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed. `marked` and `uuid` are peer dependencies because some components and utilities rely on them.
+
+## CLI Setup
+
+Use the CLI inside an existing React or Next.js project to add only the file changes Boreal UI needs: the package dependency, the global stylesheet import, `ThemeProvider`, and default style config.
+
+```bash
+npx boreal-ui@latest init
+```
+
+You can preview changes or run non-interactively:
+
+```bash
+npx boreal-ui init --dry-run
+npx boreal-ui init --framework next --yes
+npx boreal-ui init --framework next --recommended-globals
+```
+
+## Setup
+
+Import the global stylesheet once near the top of your application.
 
 ### React
 
@@ -73,6 +76,42 @@ Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or your
 import "boreal-ui/next/globals.css";
 ```
 
+If your Next.js app still has the starter `globals.css` reset below, avoid loading it after Boreal styles:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+The universal `padding` and `margin` reset can override spacing that Boreal components and nested content rely on. Prefer a narrower baseline:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+The CLI can create or repair that safer baseline for Next.js apps:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+Interactive Next.js setup prompts for this by default. Use `--recommended-globals` to apply it without the prompt, or `--no-recommended-globals` to skip it.
+
 Then import components from the Next build:
 
 ```tsx
@@ -101,7 +140,7 @@ import Card from "boreal-ui/next/Card";
 
 ## Components
 
-For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs/README.md). They cover import paths, styling and theming, common component patterns, generated prop docs, public TypeScript types, and contributor workflow.
+For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs/README.md). They cover import paths, styling and theming, common component patterns, generated prop docs, public TypeScript types, and contributor workflow.
 
 ### Actions
 
@@ -113,7 +152,7 @@ For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs
 
 - `TextInput` and `TextArea` support labels, helper/error text, validation state, disabled state, sizing, theming, and accessible descriptions.
 - `Select` and `ThemeSelect` cover option selection and color-scheme switching.
-- `Checkbox`, `RadioButton`, `RadioGroup`, `Toggle`, and `Slider` provide common controlled input patterns.
+- `Checkbox`, `RadioButton`, `RadioGroup`, `Toggle`, and `Slider` provide common controlled input patterns.
 - `ColorPicker` supports color selection flows.
 - `DateTimePicker` handles date and time input.
 - `FileUpload` supports file selection UI.
@@ -161,28 +200,28 @@ Exact props vary by component. TypeScript and the generated prop docs are the so
 
 ## Global Style Defaults
 
-Call `borealConfig` once before rendering your app to set project-wide defaults. `setBorealStyleConfig` remains available as the explicit API name.
-
-```tsx
-import { borealConfig } from "boreal-ui/core";
-
-borealConfig({
-  defaultTheme: "secondary",
-  defaultSize: "medium",
-  defaultRounding: "medium",
-  defaultShadow: "light",
-  defaultBorderWidth: "none",
-  defaultGlass: false,
-  defaultOutline: false,
-  defaultColorSchemeName: "Forest Dusk",
-});
-```
-
-For Next.js, import the same API from `boreal-ui/next`:
-
-```tsx
-import { borealConfig } from "boreal-ui/next";
-```
+Call `borealConfig` once before rendering your app to set project-wide defaults. `setBorealStyleConfig` remains available as the explicit API name.
+
+```tsx
+import { borealConfig } from "boreal-ui/core";
+
+borealConfig({
+  defaultTheme: "secondary",
+  defaultSize: "medium",
+  defaultRounding: "medium",
+  defaultShadow: "light",
+  defaultBorderWidth: "none",
+  defaultGlass: false,
+  defaultOutline: false,
+  defaultColorSchemeName: "Forest Dusk",
+});
+```
+
+For Next.js, import the same API from `boreal-ui/next`:
+
+```tsx
+import { borealConfig } from "boreal-ui/next";
+```
 
 Component props still win over global defaults:
 
@@ -217,6 +256,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
   return (
     <ThemeProvider
       customSchemes={customSchemes}
+      enableThemeScript={false}
       initialSchemeName="Cyberpunk Pulse"
     >
       {children}
@@ -227,11 +267,12 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 `ThemeProvider` props:
 
-| Prop                   | Description                                           |
-| ---------------------- | ----------------------------------------------------- |
-| `customSchemes`        | Register additional color schemes at runtime.         |
-| `initialSchemeName`    | Select an initial scheme by name.                     |
-| `useOnlyCustomSchemes` | Use only custom schemes instead of the built-in list. |
+| Prop                   | Description                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `customSchemes`        | Register additional color schemes at runtime.                                            |
+| `enableThemeScript`    | Render the pre-hydration theme script. Defaults to `true` for core and `false` for Next. |
+| `initialSchemeName`    | Select an initial scheme by name.                                                        |
+| `useOnlyCustomSchemes` | Use only custom schemes instead of the built-in list.                                    |
 
 Color scheme shape:
 
@@ -269,20 +310,20 @@ registerColorScheme({
 console.log(defaultColorSchemes.map((scheme) => scheme.name));
 ```
 
-## Generated Prop Docs
-
-Boreal UI exports generated prop metadata for documentation sites, playgrounds, or prop tables.
+## Generated Prop Docs
+
+Boreal UI exports generated prop metadata for documentation sites, playgrounds, or prop tables.
 
 ```tsx
 import { buttonPropDocs, dataTablePropDocs } from "boreal-ui/core";
 
 console.log(buttonPropDocs.name);
-console.log(dataTablePropDocs.props);
-```
-
-The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component. Prop docs include `defaultValue` when the component implementation sets a readable default.
-
-For the complete generated prop-doc export list, see [Public API Reference](./docs/public-api-reference.md).
+console.log(dataTablePropDocs.props);
+```
+
+The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component. Prop docs include `defaultValue` when the component implementation sets a readable default.
+
+For the complete generated prop-doc export list, see [Public API Reference](./docs/public-api-reference.md).
 
 ## Type Exports
 
@@ -372,9 +413,9 @@ Useful scripts:
 | `npm run audit`                | Run type, lint, style, test, build, and package checks. |
 | `npm run generate:docs`        | Regenerate component prop docs.                         |
 | `npm run generate:entrypoints` | Regenerate component entry points.                      |
-| `npm run generate:exports`     | Regenerate package exports.                             |
-
-Contributor documentation for component structure, generated docs, package output, and release checks lives in [Development Workflow](./docs/development-workflow.md).
+| `npm run generate:exports`     | Regenerate package exports.                             |
+
+Contributor documentation for component structure, generated docs, package output, and release checks lives in [Development Workflow](./docs/development-workflow.md).
 
 ## Package Entry Points
 

package/README.npm.md

@@ -0,0 +1,450 @@
+# Boreal UI
+
+Boreal UI is a customizable, accessible React and Next.js component library with SCSS-powered theming, TypeScript types, generated prop metadata, and parallel `core` and `next` package outputs.
+
+Use it when you want production-ready UI primitives that can be themed globally, customized per component, tested predictably, and imported in either standard React apps or Next.js app-router projects.
+
+## Highlights
+
+- **React and Next.js builds:** import from `boreal-ui/core` for React apps or `boreal-ui/next` for Next.js apps.
+- **Deep component set:** buttons, forms, navigation, data display, feedback, overlays, layout primitives, and utility components.
+- **Theme system:** curated color schemes, custom schemes, runtime theme selection, CSS variables, and `ThemeSelect`.
+- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig`.
+- **Accessible by default:** semantic markup, ARIA support, keyboard behavior, visible focus states, disabled states, live announcements where useful, and predictable test IDs.
+- **Styling flexibility:** theme, state, size, rounding, shadow, outline, glass, custom class names, SCSS variables, and consumer CSS overrides.
+- **Typed public API:** TypeScript component props, shared type exports, and generated prop documentation objects for docs tooling.
+
+## Installation
+
+```bash
+npm install boreal-ui
+```
+
+Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed.
+
+Some components and utilities rely on `marked` and `uuid`, so make sure they are available if your package manager does not install peer dependencies automatically.
+
+## CLI Setup
+
+Use the CLI inside an existing React or Next.js project to add the package dependency, global stylesheet import, `ThemeProvider`, and default style config.
+
+```bash
+npx boreal-ui@latest init
+```
+
+Preview changes before writing files:
+
+```bash
+npx boreal-ui init --dry-run
+```
+
+Run non-interactively:
+
+```bash
+npx boreal-ui init --framework next --yes
+```
+
+For Next.js projects, you can also apply Boreal’s recommended global CSS baseline:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+## Setup
+
+Import the global stylesheet once near the top of your application.
+
+## React
+
+```tsx
+import "boreal-ui/core/globals.css";
+```
+
+Then import components from the core build:
+
+```tsx
+import { Button, Card, TextInput } from "boreal-ui/core";
+
+export function Example() {
+  return (
+    <Card title="Welcome" theme="primary" shadow="medium">
+      <TextInput label="Project name" placeholder="Aurora dashboard" />
+      <Button theme="secondary" size="large">
+        Continue
+      </Button>
+    </Card>
+  );
+}
+```
+
+## Next.js
+
+Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or your global stylesheet.
+
+```tsx
+import "boreal-ui/next/globals.css";
+```
+
+Then import components from the Next build:
+
+```tsx
+"use client";
+
+import { Button, Card, TextInput } from "boreal-ui/next";
+
+export default function Example() {
+  return (
+    <Card title="Welcome" theme="primary" shadow="medium">
+      <TextInput label="Project name" placeholder="Aurora dashboard" />
+      <Button theme="secondary" size="large">
+        Continue
+      </Button>
+    </Card>
+  );
+}
+```
+
+### Next.js Global CSS Note
+
+If your Next.js app still has the default starter reset below, avoid loading it after Boreal styles:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+The universal `padding` and `margin` reset can override spacing that Boreal components and nested content rely on.
+
+Prefer this safer baseline:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+## Standalone Component Imports
+
+You can import individual components directly:
+
+```tsx
+import Button from "boreal-ui/core/Button";
+import Card from "boreal-ui/next/Card";
+```
+
+## Package Entry Points
+
+```tsx
+import { Button } from "boreal-ui/core";
+import Button from "boreal-ui/core/Button";
+import "boreal-ui/core/globals.css";
+
+import { Button as NextButton } from "boreal-ui/next";
+import NextCard from "boreal-ui/next/Card";
+import "boreal-ui/next/globals.css";
+```
+
+The root `boreal-ui` entry currently points to the core build. For Next.js apps, prefer `boreal-ui/next` so the Next wrappers and client directives are used.
+
+## Components
+
+### Actions
+
+- `Button`
+- `IconButton`
+- `ScrollToTop`
+
+### Forms and Inputs
+
+- `TextInput`
+- `TextArea`
+- `Select`
+- `ThemeSelect`
+- `Checkbox`
+- `RadioButton`
+- `RadioGroup`
+- `Toggle`
+- `Slider`
+- `ColorPicker`
+- `DateTimePicker`
+- `FileUpload`
+- `TagInput`
+- `FormGroup`
+
+### Data and Content
+
+- `DataTable`
+- `MarkdownRenderer`
+- `Typography`
+- `MetricBox`
+
+### Feedback and Status
+
+- `Badge`
+- `Chip`
+- `ChipGroup`
+- `Progressbar`
+- `CircularProgress`
+- `Spinner`
+- `Skeleton`
+- `Rating`
+- `Tooltip`
+- `MessagePopup`
+- `PopOver`
+- `Modal`
+- `NotificationCenter`
+- `EmptyState`
+
+### Navigation and Layout
+
+- `Navbar`
+- `Sidebar`
+- `Footer`
+- `Breadcrumbs`
+- `Tabs`
+- `Stepper`
+- `Timeline`
+- `Accordion`
+- `Pager`
+- `Toolbar`
+- `Dropdown`
+- `Divider`
+- `Card`
+- `Avatar`
+
+## Common Styling Props
+
+Many components share the same styling vocabulary:
+
+| Prop          | Values                                                    |
+| ------------- | --------------------------------------------------------- |
+| `theme`       | `primary`, `secondary`, `tertiary`, `quaternary`, `clear` |
+| `state`       | `success`, `error`, `warning`, `disabled`, empty string   |
+| `size`        | `xs`, `small`, `medium`, `large`, `xl`                    |
+| `rounding`    | `none`, `small`, `medium`, `large`, `full`                |
+| `shadow`      | `none`, `light`, `medium`, `strong`, `intense`            |
+| `borderWidth` | `none`, `xs`, `small`, `medium`, `large`, `xl`            |
+| `outline`     | outline treatment where supported                         |
+| `glass`       | translucent theme-aware surface where supported           |
+| `className`   | consumer styling hook                                     |
+| `data-testid` | stable test selector                                      |
+
+Exact props vary by component. TypeScript and the generated prop docs are the source of truth for each component.
+
+## Global Style Defaults
+
+Call `borealConfig` once before rendering your app to set project-wide defaults.
+
+```tsx
+import { borealConfig } from "boreal-ui/core";
+
+borealConfig({
+  defaultTheme: "secondary",
+  defaultSize: "medium",
+  defaultRounding: "medium",
+  defaultShadow: "light",
+  defaultBorderWidth: "none",
+  defaultGlass: false,
+  defaultOutline: false,
+  defaultColorSchemeName: "Forest Dusk",
+});
+```
+
+For Next.js, import the same API from `boreal-ui/next`:
+
+```tsx
+import { borealConfig } from "boreal-ui/next";
+```
+
+Component props still win over global defaults:
+
+```tsx
+<Button theme="primary" size="large" shadow="strong">
+  Save changes
+</Button>
+```
+
+## Theme Provider and Color Schemes
+
+`ThemeProvider` manages the active color scheme and writes the scheme into CSS variables used by Boreal UI components.
+
+```tsx
+"use client";
+
+import { ThemeProvider } from "boreal-ui/next";
+
+const customSchemes = [
+  {
+    name: "Cyberpunk Pulse",
+    primaryColor: "#ff006e",
+    secondaryColor: "#8338ec",
+    tertiaryColor: "#3a0ca3",
+    quaternaryColor: "#fb5607",
+    backgroundColor: "#0f0f0f",
+    forceTextColor: "#ffffff",
+  },
+];
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider
+      customSchemes={customSchemes}
+      enableThemeScript={false}
+      initialSchemeName="Cyberpunk Pulse"
+    >
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+### ThemeProvider Props
+
+| Prop                   | Description                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `customSchemes`        | Register additional color schemes at runtime.                                            |
+| `enableThemeScript`    | Render the pre-hydration theme script. Defaults to `true` for core and `false` for Next. |
+| `initialSchemeName`    | Select an initial scheme by name.                                                        |
+| `useOnlyCustomSchemes` | Use only custom schemes instead of the built-in list.                                    |
+
+### Color Scheme Shape
+
+```ts
+type ColorScheme = {
+  name: string;
+  primaryColor: string;
+  secondaryColor: string;
+  tertiaryColor: string;
+  quaternaryColor: string;
+  backgroundColor: string;
+  forceTextColor?: string;
+};
+```
+
+You can also register schemes manually:
+
+```tsx
+import {
+  defaultColorSchemes,
+  registerColorScheme,
+  ThemeSelect,
+} from "boreal-ui/core";
+
+registerColorScheme({
+  name: "Brand Night",
+  primaryColor: "#4f46e5",
+  secondaryColor: "#06b6d4",
+  tertiaryColor: "#a855f7",
+  quaternaryColor: "#22c55e",
+  backgroundColor: "#0f172a",
+  forceTextColor: "#ffffff",
+});
+
+console.log(defaultColorSchemes.map((scheme) => scheme.name));
+```
+
+## Type Exports
+
+Shared public types are exported from both builds:
+
+```ts
+import type {
+  BorderType,
+  ColorScheme,
+  RoundingType,
+  ShadowType,
+  SizeType,
+  ThemeType,
+} from "boreal-ui/core";
+```
+
+Standalone type entry points are also available:
+
+```ts
+import type { ThemeType } from "boreal-ui/core/types";
+import type { SizeType } from "boreal-ui/next/types";
+```
+
+## Generated Prop Docs
+
+Boreal UI exports generated prop metadata for documentation sites, playgrounds, and prop tables.
+
+```tsx
+import { buttonPropDocs, dataTablePropDocs } from "boreal-ui/core";
+
+console.log(buttonPropDocs.name);
+console.log(dataTablePropDocs.props);
+```
+
+The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component.
+
+## CSS Customization
+
+Boreal UI styles are built on CSS variables and SCSS. You can override variables globally or scope them to a subtree:
+
+```css
+:root {
+  --font-family-ui: Inter, system-ui, sans-serif;
+  --border-radius-md: 0.5rem;
+  --transition-default: 160ms ease;
+  --focus-outline-color: #2563eb;
+}
+
+.admin-shell {
+  --background-color: #0f172a;
+  --text-color: #f8fafc;
+}
+```
+
+Most components also accept `className`, and larger components expose section-level class props such as:
+
+```tsx
+<Card
+  title="Custom Card"
+  className="dashboard-card"
+  headerClassName="dashboard-card__header"
+  contentClassName="dashboard-card__content"
+  footerClassName="dashboard-card__footer"
+/>
+```
+
+## Accessibility and Testing
+
+Boreal UI is designed for Testing Library, Jest, jest-axe, Cypress, and Storybook workflows.
+
+- Prefer roles and accessible names in tests.
+- Use `data-testid` when a stable selector is needed.
+- Icon-only controls should receive an accessible label.
+- Helper and error text are connected with ARIA where components support those states.
+- Interactive components are built with keyboard behavior and visible focus states in mind.
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { Button } from "boreal-ui/core";
+
+it("renders an accessible button", () => {
+  render(<Button>Submit</Button>);
+  expect(screen.getByRole("button", { name: /submit/i })).toBeInTheDocument();
+});
+```
+
+## Documentation
+
+For full documentation, examples, and API guides, [View the Boreal UI docs](https://www.borealui.ca)
+
+## License
+
+MIT © Davin Chiupka