@brandrail/kit 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,19 @@
+# @brandrail/kit licence
+
+Copyright © 2026 Thiago Baptistella. All rights reserved.
+
+This package is proprietary software. It is published on npm so that customers of Brandrail
+(https://www.brandrail.com.au) can install it; publication does not make it open source.
+
+1. **Use.** You may install and use this package, unmodified, in applications you build, for as long as you
+   (or the organisation you work for) have a Brandrail account and comply with the Brandrail Terms of Service.
+   You may also evaluate it for up to 30 days without an account.
+2. **Restrictions.** You may not sell, sublicense or redistribute the package or any part of it on its own
+   (for example as a component library, template or design kit), modify it and distribute the result, or
+   remove this notice. Shipping it inside your own application's built output is allowed.
+3. **No warranty.** The package is provided "as is", without warranty of any kind. To the extent permitted by law,
+   the author is not liable for any claim, damages or other liability arising from its use.
+4. **Termination.** These rights end automatically if you breach these terms or your Brandrail account ends,
+   except for application builds already deployed.
+
+Questions: support@brandrail.com.au

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @brandrail/kit
 
-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.
+The Brandrail UI kit: React components, and the same components as custom elements for any framework. They follow your Brand Kit through CSS variables.
+
+## Install
+
+```bash
+npm i @brandrail/kit
+```
+
+React apps also need `react` and `react-dom` 19. Angular, Vue and plain HTML apps use the custom elements (below) and need nothing else. Use is covered by [LICENSE.md](LICENSE.md): free with a Brandrail account.
+
+## Use
+
+```tsx
+import "@brandrail/kit/styles.css";
+import "./brandrail.tokens.css"; // written by `npx brandrail init`: maps your Brand Kit onto the kit
+import { Button, ColorMode } from "@brandrail/kit";
+
+export default function App() {
+  return (
+    <div className="brandrail light">
+      <Button theme="brandrail" colorMode={ColorMode.LIGHT} label="Save" />
+    </div>
+  );
+}
+```
+
+`brandrail init` writes `brandrail.tokens.css` with your published Brand Kit: colours, spacing, radius, type and font. The kit picks them up automatically, whatever order the stylesheets load in.
+
+## Use in any framework (custom elements)
+
+Every component is also a custom element: `Button` is `<br-button>`, `DatePicker` is `<br-date-picker>`, and so on (`br-` + the name in kebab-case). One import registers them all; it carries its own small React-compatible runtime (Preact), so the page needs no React. About 59 KB gzipped for all 28.
+
+```js
+import "@brandrail/kit/elements";   // once, at the app entry
+import "./brandrail.tokens.css";    // from `npx brandrail init`: your Brand Kit
+```
+
+- **Attributes** are the React props in kebab-case: `<br-button label="Save" type="cta" size="small">`. Lists and objects take JSON (`items='[{"label":"Home"}]'`) or a property (`el.items = [...]`).
+- **Events** are the callback props as DOM events with the value in `event.detail`: `onChange` → `br-change`, `onClick` → `br-click`. Inputs, checkboxes, toggles, dropdowns and date pickers keep their own value, and expose it as a property (`el.value`, `el.checked`, `el.selected`, `el.selectedDate`).
+- **Children**: containers take kit elements: `<br-button-group><br-button label="Day"></br-button-group>`, `<br-dropdown><br-list-item label="Brake" value="brake"></br-dropdown>`, `<br-radio-group>` with `<br-radio>`, `<br-checkbox-group>` with `<br-checkbox>`. `<br-tooltip content="…">` wraps any content.
+- **Theme**: `theme="brandrail"` is the default; dark mode with `color-mode="dark"` or a `dark` class on any ancestor.
+- **Styles** are added to the page once by the import. With a strict Content Security Policy (no inline styles), link `dist/styles.css` yourself with a `data-brandrail-kit` attribute and nothing is injected.
+
+**Angular** (any version with Ivy, including 14):
+
+```ts
+@NgModule({ /* … */ schemas: [CUSTOM_ELEMENTS_SCHEMA] })   // or in a standalone component's `schemas`
+```
+```html
+<br-input-text label="Truck ID" [value]="id" (br-change)="id = $any($event).detail"></br-input-text>
+<br-breadcrumb [items]="crumbs"></br-breadcrumb>
+<!-- Angular types $event on unknown elements as Event: read the value with $any($event).detail. -->
+```
+
+**Vue 3**: tell the compiler the tags are custom elements, then bind as usual:
+
+```js
+// vite.config.js
+vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("br-") } } })
+```
+```html
+<br-toggle label="Alerts" :checked="on" @br-change="on = $event.detail" />
+```
+
+**Plain HTML, PHP, Twig, Mustache**: copy `dist/elements.js` into your assets and load it once with `<script type="module" src="/assets/elements.js"></script>`.
+
+Editors: `custom-elements.json` (in the package) gives VS Code and JetBrains attribute completion; `dist/elements-tags.d.ts` types `document.querySelector("br-button")`.
+
+## Publishing (maintainers)
+
+Published to the public npm registry as `@brandrail/kit` (built files only: minified, no source maps, no TypeScript source; the script refuses to publish if any slip in). Needs an npm account in the `brandrail` npm organisation (`npm login` first).
+
+```bash
+cd packages/kit
+pnpm run publish:npm -- --dry-run   # lists exactly what would be published
+pnpm run publish:npm
+```
+
+Bump `version` in `package.json` before each release. Inside the monorepo the web app uses the TypeScript source directly. (`publish:github` still publishes the old private GitHub Packages copy.)