@brilo/base-blocks 0.1.0

package/docs/block-anatomy.md

@@ -0,0 +1,73 @@
+# 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

@@ -0,0 +1,204 @@
+# 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

@@ -0,0 +1,179 @@
+# 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/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@brilo/base-blocks",
+  "version": "0.1.0",
+  "author": "Brilo",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "watch": "tsc --watch",
+    "lint": "biome lint ./src",
+    "format": "biome format --write ./src && prettier --write \"./src/**/*.scss\"",
+    "check": "biome check --write ./src"
+  },
+  "peerDependencies": {
+    "@wordpress/block-editor": "15.21.0",
+    "@wordpress/blocks": "15.21.0",
+    "@wordpress/components": "35.0.0",
+    "@wordpress/i18n": "6.21.0",
+    "react": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@types/react": "^18.3.12",
+    "@types/wordpress__block-editor": "^15.0.6",
+    "@wordpress/block-editor": "^15.21.0",
+    "@wordpress/blocks": "^15.21.0",
+    "@wordpress/components": "^35.0.0",
+    "@wordpress/data": "^10.48.0",
+    "@wordpress/element": "^8.0.0",
+    "@wordpress/i18n": "^6.21.0",
+    "prettier": "^3.0.0",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/blocks/column/column-group/edit.tsx

@@ -0,0 +1,56 @@
+import {InspectorControls} from '@wordpress/block-editor'
+import {PanelBody, RangeControl} from '@wordpress/components'
+import {__} from '@wordpress/i18n'
+import {useGroupBlock} from '~/hooks/useGroupBlock'
+import type {ColumnGroupAttributes, ColumnGroupOptions} from './types'
+
+export function createColumnGroupEdit(options: ColumnGroupOptions) {
+  return function Edit({
+    attributes,
+    setAttributes,
+  }: {
+    attributes: ColumnGroupAttributes
+    setAttributes: (a: Partial<ColumnGroupAttributes>) => void
+  }) {
+    const {spacingX, spacingY} = attributes
+    const {blockProps, innerBlocksProps} = useGroupBlock({
+      blockClassName: options.blockClassName ?? 'g-column wp-block-section',
+      containerClassName: options.containerClassName ?? 'g-column__inner',
+      allowedBlocks: options.allowedBlocks,
+      template: options.template,
+      layout: {type: 'default'},
+      containerStyle: {
+        '--gap-x': `${spacingX}px`,
+        '--gap-y': `${spacingY}px`,
+      },
+    })
+
+    return (
+      <>
+        <InspectorControls>
+          <PanelBody title={__('Nastavení sloupců', 'brilo-blocks')}>
+            <RangeControl
+              label={__('Horizontální mezera (px)', 'brilo-blocks')}
+              value={spacingX}
+              onChange={(v) => setAttributes({spacingX: v ?? 0})}
+              min={0}
+              max={64}
+              step={8}
+            />
+            <RangeControl
+              label={__('Vertikální mezera (px)', 'brilo-blocks')}
+              value={spacingY}
+              onChange={(v) => setAttributes({spacingY: v ?? 0})}
+              min={0}
+              max={64}
+              step={8}
+            />
+          </PanelBody>
+        </InspectorControls>
+        <div {...blockProps}>
+          <div {...innerBlocksProps} />
+        </div>
+      </>
+    )
+  }
+}

package/src/blocks/column/column-group/editor.scss

@@ -0,0 +1,7 @@
+@layer base {
+  .g-column__inner {
+    display: grid;
+    grid-template-columns: repeat(12, minmax(0, 1fr));
+    gap: var(--gap-y) var(--gap-x);
+  }
+}

package/src/blocks/column/column-group/factory.tsx

@@ -0,0 +1,29 @@
+import {InnerBlocks} from '@wordpress/block-editor'
+import type {BlockConfiguration} from '@wordpress/blocks'
+import {__} from '@wordpress/i18n'
+import {createColumnGroupEdit} from './edit'
+import type {ColumnGroupAttributes, ColumnGroupOptions} from './types'
+
+export function createColumnGroupBlock(options: ColumnGroupOptions): BlockConfiguration<ColumnGroupAttributes> {
+  return {
+    name: options.name,
+    title: options.title ?? __('Obsahové sloupce', 'brilo-blocks'),
+    description: options.description,
+    category: options.category ?? 'layout',
+    ...(options.parent && {parent: options.parent}),
+    icon: options.icon ?? 'columns',
+    supports: {html: false, customClassName: false},
+    attributes: {
+      spacingX: {
+        type: 'number',
+        default: 16,
+      },
+      spacingY: {
+        type: 'number',
+        default: 16,
+      },
+    },
+    edit: createColumnGroupEdit(options),
+    save: () => <InnerBlocks.Content />,
+  } as BlockConfiguration<ColumnGroupAttributes>
+}

package/src/blocks/column/column-group/index.ts

@@ -0,0 +1,14 @@
+export type {ColumnGroupAttributes, ColumnGroupOptions} from './types'
+export {createColumnGroupBlock} from './factory'
+
+import type {ColumnGroupOptions} from './types'
+
+export const columnGroupDefaults: ColumnGroupOptions = {
+  name: 'brilo/column-group',
+  allowedBlocks: ['brilo/column-item'],
+  parent: ['brilo/base-section'],
+  template: [
+    ['brilo/column-item', {}],
+    ['brilo/column-item', {}],
+  ],
+}

package/src/blocks/column/column-group/types.ts

@@ -0,0 +1,8 @@
+import type {BriloBlockType} from '~/types'
+
+export interface ColumnGroupAttributes extends Record<string, unknown> {
+  spacingX: number
+  spacingY: number
+}
+
+export interface ColumnGroupOptions extends BriloBlockType {}

package/src/blocks/column/column-item/constants.ts

@@ -0,0 +1 @@
+export const SIZES = ['1/4', '1/3', '1/2', '2/3', '3/4', '1/1']

package/src/blocks/column/column-item/edit.tsx

@@ -0,0 +1,48 @@
+import {InspectorControls} from '@wordpress/block-editor'
+import {PanelBody, RangeControl} from '@wordpress/components'
+import {__} from '@wordpress/i18n'
+import clsx from 'clsx'
+import {useGroupBlock} from '~/hooks/useGroupBlock'
+import type {ColumnItemAttributes, ColumnItemOptions} from './types'
+import {SIZES} from './constants'
+
+export function createColumnItemEdit(options: ColumnItemOptions) {
+  return function Edit({
+    attributes,
+    setAttributes,
+  }: {
+    attributes: ColumnItemAttributes
+    setAttributes: (a: Partial<ColumnItemAttributes>) => void
+  }) {
+    const {size} = attributes
+    const {blockProps, innerBlocksProps} = useGroupBlock({
+      blockClassName: clsx(options.blockClassName ?? 'i-column', `--size-${size}`),
+      containerClassName: options.containerClassName ?? 'i-column__inner',
+      allowedBlocks: options.allowedBlocks,
+      template: options.template,
+    })
+
+    const sizeIndex = SIZES.indexOf(size)
+
+    return (
+      <>
+        <InspectorControls>
+          <PanelBody title={__('Nastavení položky sloupce', 'brilo-blocks')}>
+            <RangeControl
+              label={__('Šířka sloupce', 'brilo-blocks')}
+              value={sizeIndex}
+              onChange={(v) => setAttributes({size: SIZES[v as number]})}
+              min={0}
+              max={SIZES.length - 1}
+              withInputField={false}
+              marks={SIZES.map((s, i) => ({label: s, value: i}))}
+            />
+          </PanelBody>
+        </InspectorControls>
+        <div {...blockProps}>
+          <div {...innerBlocksProps} />
+        </div>
+      </>
+    )
+  }
+}