@brilo/base-blocks 0.1.0 → 0.1.2

package/docs/block-anatomy.md

@@ -1,73 +0,0 @@
-# Block anatomy
-
-Every block in `@brilo/base-blocks` consists of exactly these files:
-
-```
-blocks/<category>/<block-name>/
-├── factory.tsx      — block config, attributes, options interface
-├── edit.tsx         — editor component (createXxxEdit)
-├── constants.ts     — option arrays and defaults used in edit.tsx
-├── index.ts         — barrel export
-└── editor.scss      — editor-only styles
-```
-
-## Categories
-
-| Category   | Purpose                                        | Example            |
-|------------|------------------------------------------------|--------------------|
-| `core/`    | Atomic blocks — no inner blocks                | `basic-button`     |
-| `groups/`  | Container blocks — wrap inner blocks           | `usp-group`        |
-| `items/`   | Item blocks — live inside a group              | `usp-item`         |
-| `sections/`| Top-level page sections — wrap groups          | `base-section`     |
-
-Use `core/` for anything that renders a single element (text, button, image).
-Use `groups/` when the block contains `InnerBlocks`.
-Use `items/` when the block is designed to be a child of a specific group (`parent` restriction).
-Use `sections/` for full-width page sections.
-
-## factory.tsx
-
-Exports:
-- `XxxAttributes` — attribute interface extending `Record<string, unknown>`
-- `XxxOptions` — options passed to the factory at tenant registration time
-- `createXxxBlock(options)` — returns `BlockConfiguration<XxxAttributes>`
-- `xxxDefaults` — sensible default options object
-
-The factory sets: `name`, `title`, `category`, `supports`, `attributes`, `edit`, `save`.
-Tenant-customisable values live in `XxxOptions`. Hardcoded values never need to change across tenants.
-
-## edit.tsx
-
-Exports a single function `createXxxEdit(options: XxxOptions)` that returns a React component.
-
-Rules:
-- No inline constant arrays — all arrays live in `constants.ts`
-- No `__` calls on module level — only inside the returned component or in `constants.ts`
-- Imports only from `./constants`, `./factory`, and `@wordpress/*`
-
-## constants.ts
-
-Contains all option arrays (`SelectOption[]`, `readonly number[]`, `readonly string[]`) used by `edit.tsx`.
-
-Rules:
-- Block-specific constants defined locally
-- Constants shared with other blocks imported from `../../../constants` (or `../../constants` for items)
-- Naming conflict resolved with import alias: `import { HEADING_LEVELS as SHARED_HEADING_LEVELS } from '../../../constants'`
-
-See [conventions.md](./conventions.md) for naming rules.
-
-## index.ts
-
-Re-exports everything needed by `src/index.ts`:
-
-```ts
-export type {XxxAttributes, XxxOptions} from './factory'
-export {createXxxBlock, xxxDefaults} from './factory'
-```
-
-`edit.tsx` and `constants.ts` are never exported from `index.ts`.
-
-## editor.scss
-
-Editor-only styles scoped to the block. Do not put frontend styles here.
-Compiled output is imported via `src/editor.scss` barrel.

package/docs/conventions.md

@@ -1,204 +0,0 @@
-# Conventions
-
-## Naming
-
-### Files
-```
-factory.tsx        — always this exact name
-edit.tsx           — always this exact name
-constants.ts       — always this exact name
-index.ts           — always this exact name
-editor.scss        — always this exact name
-```
-
-### Functions and types
-
-| Thing             | Pattern                  | Example                    |
-|-------------------|--------------------------|----------------------------|
-| Factory function  | `createXxxBlock`         | `createBasicButtonBlock`   |
-| Edit factory      | `createXxxEdit`          | `createBasicButtonEdit`    |
-| Attributes type   | `XxxAttributes`          | `BasicButtonAttributes`    |
-| Options type      | `XxxOptions`             | `BasicButtonOptions`       |
-| Defaults object   | `xxxDefaults`            | `basicButtonDefaults`      |
-
-### Constants
-
-All-caps snake case. No `DEFAULT_` prefix unless the constant is a fallback for an overridable option.
-
-```ts
-// Overridable option default → DEFAULT_ prefix
-export const DEFAULT_VARIANTS = [...] as const
-
-// Fixed set, not exposed in options → no prefix
-export const HEADING_LEVELS = [1, 2, 3, 4] as const
-```
-
-Shared constants in `src/constants.ts`: `HEADING_LEVELS`, `HEADING_STYLES`, `CONTENT_SIZES`.
-Import directly from `../../../constants` in block `constants.ts` files. Use alias on name conflict.
-
-## Types
-
-`SelectOption` — use for any `{value, label}` pair. Import from `src/types.ts`:
-```ts
-import type {SelectOption} from '../../../types'
-```
-
-`readonly number[]` / `readonly string[]` — use `as const` for level/style arrays that must match TS literal types.
-
-### Derived union types from constants
-
-Allowed values for block attributes are derived directly from `as const` arrays in `constants.ts`. Never write union types by hand.
-
-```
-constants.ts (as const arrays)
-  → derived union types in types.ts
-    → XxxAttributes interface
-      → consumed by edit.tsx (attributes + setAttributes)
-```
-
-Pattern:
-```ts
-// constants.ts
-export const MEDIA_POSITIONS = [
-  {value: 'left', label: ...},
-  {value: 'right', label: ...},
-] as const
-
-// types.ts
-export type MediaPositions = (typeof MEDIA_POSITIONS)[number]['value']
-// → 'left' | 'right'
-```
-
-For plain number/string arrays without `value` key (e.g. `HEADING_LEVELS = [1, 2, 3, 4] as const`):
-```ts
-export type HeadingLevels = (typeof HEADING_LEVELS)[number]
-// → 1 | 2 | 3 | 4
-```
-
-To add or remove an allowed value, edit the source constant — the type updates automatically.
-
-## Options pattern
-
-Every factory accepts an `XxxOptions` object. Options that can be overridden by tenants have defaults defined in `constants.ts` and applied with `??`:
-
-```ts
-export function createXxxEdit(options: XxxOptions) {
-  const variants = options.variants ?? DEFAULT_VARIANTS
-  // ...
-}
-```
-
-The same resolved array is used for both the WordPress `attributes.enum` definition and the edit UI — never hardcode `DEFAULT_*` directly in the factory `attributes` object:
-
-```ts
-// ✓ correct — uses resolved value, reflects tenant override
-const variants = options.variants ?? DEFAULT_VARIANTS
-attributes: { variant: { enum: variants.map((v) => v.value) } }
-
-// ✗ wrong — ignores tenant override
-attributes: { variant: { enum: DEFAULT_VARIANTS.map((v) => v.value) } }
-```
-
-Options that are mandatory (like `name`) have no default and are required in the interface.
-
-## Generic factories
-
-Every factory whose options contain overridable enum arrays is generic. This lets TypeScript narrow attribute value types to the exact set a tenant provides.
-
-```ts
-// factory.tsx
-export function createBasicButtonBlock<
-  TVariants extends OptionArray = typeof DEFAULT_VARIANTS,
-  TSizes extends OptionArray = typeof DEFAULT_SIZES,
->(
-  options: BasicButtonOptions<TVariants, TSizes>,
-): BlockConfiguration<BasicButtonAttributes<TVariants[number]['value'], TSizes[number]['value']>>
-```
-
-```ts
-// types.ts — Options and Attributes are also generic with matching defaults
-export interface BasicButtonAttributes<
-  TVariant extends string = ButtonVariant,
-  TSize extends string = ButtonSize,
-> extends Record<string, unknown> {
-  variant: TVariant
-  size: TSize
-}
-
-export interface BasicButtonOptions<
-  TVariants extends OptionArray = typeof DEFAULT_VARIANTS,
-  TSizes extends OptionArray = typeof DEFAULT_SIZES,
-> {
-  variants?: TVariants
-  sizes?: TSizes
-}
-```
-
-Use the shared constraint types from `src/types.ts`:
-
-| Constraint | Use for |
-|---|---|
-| `OptionArray` | `ReadonlyArray<{value: string; label: string}>` — SelectOption arrays |
-| `NumberArray` | `ReadonlyArray<number>` — level arrays |
-| `StringArray` | `ReadonlyArray<string>` — style/class arrays |
-
-**Tenant usage** — base (no generics needed, defaults inferred):
-```ts
-createBasicButtonBlock({...basicButtonDefaults})
-// variant: 'primary' | 'secondary'
-```
-
-**Tenant usage** — custom enum:
-```ts
-const MY_VARIANTS = [
-  {value: 'primary', label: 'Primární'},
-  {value: 'brand', label: 'Brand'},
-] as const  // as const is required for literal inference
-
-createBasicButtonBlock({...basicButtonDefaults, variants: MY_VARIANTS})
-// variant: 'primary' | 'brand'
-```
-
-`edit.tsx` stays non-generic — `createXxxEdit` takes the non-generic `XxxOptions` type. The factory casts options when calling it:
-```ts
-edit: createBasicButtonEdit(options as unknown as BasicButtonOptions),
-```
-
-Fixed arrays that are not exposed in options (e.g. `HEADING_LEVELS`, `CHIP_POSITIONS`) are not type params — they remain hardcoded in `attributes` and render.
-
-## Exports
-
-Only `factory.tsx` exports from a block. `edit.tsx` and `constants.ts` are internal.
-
-`src/index.ts` re-exports:
-- Types: `XxxAttributes`, `XxxOptions`
-- Values: `createXxxBlock`, `xxxDefaults`
-
-Do not export `SelectOption` from individual factory files — it lives in `src/types.ts` and is exported from there.
-
-## CSS class composition
-
-Use `clsx` to compose `className` in `useBlockProps`. Each modifier class reflects a piece of component state — readable and styleable per state:
-
-```tsx
-const blockProps = useBlockProps({
-  className: clsx(
-    options.blockClassName ?? 'i-button',
-    `--variant-${variant}`,
-    `--size-${size}`,
-    outline && '--outline',
-    fullWidth !== 'false' && `--full-width-${fullWidth}`,
-  ),
-})
-```
-
-Rules:
-- Base class first (from `options.blockClassName` or block default)
-- BEM modifier classes (`--variant-x`, `--size-x`) as template literals
-- Boolean modifiers as `condition && '--class'` — falsy values dropped by `clsx`
-- No manual string concatenation or ternaries for class toggling
-
-## i18n
-
-All user-visible strings use `__('string', 'brilo-blocks')`.
-Constants with translated labels live in `constants.ts`, not in `edit.tsx`.

package/docs/new-block.md

@@ -1,179 +0,0 @@
-# Adding a new block
-
-## 1. Choose a category
-
-See [block-anatomy.md](./block-anatomy.md#categories) for when to use `core/`, `groups/`, `items/`, or `sections/`.
-
-## 2. Create the directory
-
-```
-src/blocks/<category>/<block-name>/
-```
-
-## 3. Create the files
-
-Copy the templates below into the directory. Replace every `Xxx` / `xxx` / `block-name` with your block name.
-
----
-
-### `factory.tsx`
-
-```tsx
-import type {BlockConfiguration} from '@wordpress/blocks'
-import {createXxxEdit} from './edit'
-
-export interface XxxAttributes extends Record<string, unknown> {
-  // TODO: define attributes
-}
-
-export interface XxxOptions {
-  name: string
-  title?: string
-  description?: string
-  category?: string
-  blockClassName?: string
-  // TODO: add overridable options
-}
-
-export const xxxDefaults: XxxOptions = {
-  name: 'brilo/xxx',
-  title: 'TODO: Block title',
-  // TODO: fill defaults
-}
-
-export function createXxxBlock(options: XxxOptions): BlockConfiguration<XxxAttributes> {
-  return {
-    name: options.name,
-    title: options.title ?? 'TODO',
-    description: options.description,
-    category: options.category ?? 'common',
-    supports: {html: false, customClassName: false},
-    attributes: {
-      // TODO: mirror XxxAttributes shape
-    },
-    edit: createXxxEdit(options),
-    save: () => null,
-  } as unknown as BlockConfiguration<XxxAttributes>
-}
-```
-
----
-
-### `constants.ts`
-
-```ts
-import {__} from '@wordpress/i18n'
-import type {SelectOption} from '../../../types'
-
-// Import shared constants if needed:
-// export {HEADING_LEVELS, HEADING_STYLES, CONTENT_SIZES} from '../../../constants'
-
-// TODO: define block-specific constants
-// export const MY_OPTIONS: SelectOption[] = [
-//   {value: 'foo', label: __('Foo', 'brilo-blocks')},
-// ]
-```
-
----
-
-### `edit.tsx`
-
-```tsx
-import {InspectorControls, useBlockProps} from '@wordpress/block-editor'
-import {PanelBody} from '@wordpress/components'
-import {__} from '@wordpress/i18n'
-import type {XxxAttributes, XxxOptions} from './factory'
-// import {MY_OPTIONS} from './constants'
-
-export function createXxxEdit(options: XxxOptions) {
-  return function Edit({
-    attributes,
-    setAttributes,
-  }: {
-    attributes: XxxAttributes
-    setAttributes: (a: Partial<XxxAttributes>) => void
-  }) {
-    const blockProps = useBlockProps({className: options.blockClassName ?? 'TODO'})
-
-    return (
-      <>
-        <InspectorControls>
-          <PanelBody title={__('TODO', 'brilo-blocks')}>
-            {/* TODO: add controls */}
-          </PanelBody>
-        </InspectorControls>
-        <div {...blockProps}>
-          {/* TODO: render block */}
-        </div>
-      </>
-    )
-  }
-}
-```
-
-For group blocks (with inner blocks), use `useGroupBlock` instead of `useBlockProps`:
-
-```tsx
-import {useGroupBlock} from '../../../hooks/useGroupBlock'
-
-const {blockProps, innerBlocksProps} = useGroupBlock({
-  blockClassName: options.blockClassName ?? 'g-xxx wp-block-section',
-  allowedBlocks: options.allowedBlocks,
-  template: options.template,
-})
-```
-
----
-
-### `index.ts`
-
-```ts
-export type {XxxAttributes, XxxOptions} from './factory'
-export {createXxxBlock, xxxDefaults} from './factory'
-```
-
----
-
-### `editor.scss`
-
-```scss
-.TODO-block-class {
-  // editor-only styles
-}
-```
-
----
-
-## 4. Register in src/index.ts
-
-```ts
-export type {XxxAttributes, XxxOptions} from './blocks/<category>/xxx'
-export {createXxxBlock, xxxDefaults} from './blocks/<category>/xxx'
-```
-
-## 5. Import in src/editor.scss
-
-```scss
-@import './blocks/<category>/<block-name>/editor';
-```
-
-## 6. Build
-
-```bash
-bun run build
-```
-
-## 7. Register in tenant
-
-```ts
-import {createXxxBlock, xxxDefaults} from '@brilo/base-blocks'
-import {registerBlockType} from '@wordpress/blocks'
-
-const config = createXxxBlock({
-  ...xxxDefaults,
-  // override what the tenant needs
-})
-registerBlockType(config.name as string, config)
-```
-
-Add `block.json` in the tenant with only build metadata (`$schema`, `apiVersion`, `name`, `editorScript`, `editorStyle`).

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2019",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "jsx": "react-jsx",
-    "outDir": "./build",
-    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "baseUrl": ".",
-    "paths": {
-      "~/*": ["./src/*"]
-    }
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "build"]
-}