@brilo/base-blocks 0.1.0 → 0.1.1

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/src/blocks/column/column-group/edit.tsx

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

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

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

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

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

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

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

@@ -1,48 +0,0 @@
-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>
-      </>
-    )
-  }
-}

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

@@ -1,34 +0,0 @@
-@layer base {
-  .i-column {
-    border: 1px dashed #0073aa;
-    box-sizing: border-box;
-    border-radius: 4px;
-    padding: 4px;
-    min-height: 64px;
-    margin: 0 !important;
-
-    &.--size-1\/4 {
-      grid-column: span 3;
-    }
-
-    &.--size-1\/3 {
-      grid-column: span 4;
-    }
-
-    &.--size-1\/2 {
-      grid-column: span 6;
-    }
-
-    &.--size-2\/3 {
-      grid-column: span 8;
-    }
-
-    &.--size-3\/4 {
-      grid-column: span 9;
-    }
-
-    &.--size-1\/1 {
-      grid-column: span 12;
-    }
-  }
-}

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

@@ -1,25 +0,0 @@
-import {InnerBlocks} from '@wordpress/block-editor'
-import type {BlockConfiguration} from '@wordpress/blocks'
-import {__} from '@wordpress/i18n'
-import {createColumnItemEdit} from './edit'
-import type {ColumnItemAttributes, ColumnItemOptions} from './types'
-
-export function createColumnItemBlock(options: ColumnItemOptions): BlockConfiguration<ColumnItemAttributes> {
-  return {
-    name: options.name,
-    title: options.title ?? __('Položka sloupce', 'brilo-blocks'),
-    description: options.description,
-    category: options.category ?? 'layout',
-    ...(options.parent && {parent: options.parent}),
-    icon: options.icon ?? 'column',
-    supports: {html: false, customClassName: false},
-    attributes: {
-      size: {
-        type: 'string',
-        default: '1/2',
-      },
-    },
-    edit: createColumnItemEdit(options),
-    save: () => <InnerBlocks.Content />,
-  } as BlockConfiguration<ColumnItemAttributes>
-}