Editable Card

# Brok UI: Editable Card (`editable-card`)

An inline-editable dashed text card with a label, an editable textarea, and edit/save affordances.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add editable-card
```

## Usage

```blade
<x-ui.editable-card
    label="Notes"
    value="Add any context you want the team to remember. Click the pencil to edit."
    placeholder="Type your notes…"
    class="mx-auto w-full max-w-xl"
/>
```

## Props

- `label` (string, default `Notes`) — Heading shown above the text and used to build the edit button's accessible name.
- `value` (string, default ``) — Initial text content.
- `placeholder` (string, default `Type here…`) — Text shown when the value is empty, both in read mode and as the textarea placeholder.
- `editable` (bool, default `true`) — When false, hides the edit button and renders the card as read-only text.

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Showing a labelled block of free-text notes that a user can edit inline without navigating to a separate form.
- Needing an explicit edit/save/cancel flow so a draft is discarded unless the user confirms it.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- The field belongs to a larger form that submits as a whole; use textarea directly inside the form.
- The content is read-only; a plain card or surface is lighter weight.

## Anti-patterns

- Turning every object into a card

## Rules

- Use the `<brok:editable-card>` tag (or `<x-ui.editable-card>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/editable-card
- Registry JSON (files, props, contract): https://brokui.dev/r/open/editable-card.json

@props([
    'label' => 'Notes',
    'value' => '',
    'placeholder' => 'Type here…',
    'editable' => true,
])

{{--
    Editable card — a dashed card showing a block of text. When editable, a pencil
    button swaps the read-only text for a <textarea> with Save/Cancel. Save commits
    the draft and emits `editable-card-change`; Cancel restores the previous text.
--}}
<div
    x-data="uiEditableCard({ text: @js($value), editable: {{ $editable ? 'true' : 'false' }} })"
    data-slot="editable-card"
    aria-label="{{ __($label) }}"
    {{ $attributes->merge(['class' => 'rounded-lg border border-dashed border-border bg-card/50 p-6 text-foreground']) }}
>
    <div class="mb-2 flex items-center justify-between gap-2">
        <span class="text-xs font-medium uppercase tracking-wide text-muted-foreground">{{ __($label) }}</span>
        @if ($editable)
            <button
                type="button"
                x-show="!editing"
                @click="edit()"
                aria-label="{{ __('Edit :label', ['label' => __($label)]) }}"
                class="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
            >
                <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z"/></svg>
            </button>
        @endif
    </div>

    <p x-show="!editing" class="whitespace-pre-wrap text-sm text-muted-foreground" x-text="text || @js(__($placeholder))"></p>

    <div x-show="editing" x-cloak class="space-y-2">
        <x-ui.textarea
            x-ref="field"
            x-model="draft"
            :rows="4"
            placeholder="{{ __($placeholder) }}"
            aria-label="{{ __($label) }}"
            class="resize-y"
        />
        <div class="flex justify-end gap-2">
            <button
                type="button"
                @click="cancel()"
                class="rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
            >{{ __('Cancel') }}</button>
            <button
                type="button"
                @click="save()"
                class="rounded-md bg-primary px-3 py-2 text-sm text-primary-foreground transition-colors hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
            >{{ __('Save') }}</button>
        </div>
    </div>
</div>

/**
 * Editable card behavior.
 *
 * Toggles between a read-only display of `text` and an edit mode backed by
 * `draft`. edit() copies text into draft and focuses the textarea; save()
 * commits the draft (dispatching `editable-card-change`); cancel() discards.
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiEditableCard', (cfg = {}) => ({
        text: cfg.text ?? '',
        editable: cfg.editable ?? true,
        editing: false,
        draft: '',

        edit() {
            if (!this.editable) {
                return;
            }
            this.draft = this.text;
            this.editing = true;
            this.$nextTick(() => this.$refs.field?.focus());
        },

        save() {
            this.text = this.draft;
            this.editing = false;
            this.$el.dispatchEvent(
                new CustomEvent('editable-card-change', {
                    detail: { value: this.text },
                    bubbles: true,
                })
            );
        },

        cancel() {
            this.draft = this.text;
            this.editing = false;
        },
    }));
});