create-nevela 0.7.1 → 0.9.1

package/template/laravel/src/Support/Descriptor.php

@@ -12,7 +12,18 @@ use JsonException;
  */
 final class Descriptor
 {
-    /** @param array<string, Field> $fields keyed by field name, in declaration order */
+    /** What a record's id can be: a UUID, which is what Nevela makes, or the auto-incrementing integer of `$table->id()`. */
+    public const ID_TYPES = ['uuid', 'int'];
+
+    /**
+     * @param  array<string, Field>  $fields  keyed by field name, in declaration order
+     * @param  string  $idType  "uuid" or "int". Chosen when the resource is made: changing it later means migrating the table yourself.
+     * @param  bool  $adopted  The table was there before Nevela, so no migration is written to create it
+     * @param  array<string, Action>  $actions  What can be done to a record or to the list beyond create, edit and delete, by name
+     * @param  PublicAccess|null  $public  What of it anyone may read or create without signing in. Nothing, when null.
+     * @param  string|null  $publish  The date-and-time field that says when a record is published: empty is a draft, a time to come is scheduled
+     * @param  string|null  $blog  Where on the site its public records are a blog, e.g. "/blog". The pages are written by `nevela:blog`.
+     */
     public function __construct(
         public readonly string $name,
         public readonly array $fields,
@@ -23,20 +34,59 @@ final class Descriptor
         public readonly ?string $icon = null,
         public readonly ?string $group = null,
         public readonly ?string $titleField = null,
+        public readonly string $idType = 'uuid',
+        public readonly bool $adopted = false,
+        public readonly array $actions = [],
+        public readonly ?PublicAccess $public = null,
+        public readonly ?string $publish = null,
+        public readonly ?string $blog = null,
     ) {
         if (! preg_match('/^[A-Z][A-Za-z0-9]*$/', $name)) {
             throw new InvalidArgumentException('Resource name must be PascalCase, e.g. Product or BlogPost.');
         }
+        if (! in_array($idType, self::ID_TYPES, true)) {
+            throw new InvalidArgumentException("\"{$idType}\" is not an id type. Use uuid or int.");
+        }
         if ($fields === []) {
             throw new InvalidArgumentException("Resource {$name} needs at least one field.");
         }
         if ($titleField !== null && ! isset($fields[$titleField])) {
             throw new InvalidArgumentException("titleField \"{$titleField}\" is not a field of {$name}.");
         }
+        $keys = [];
+        foreach ($actions as $action) {
+            foreach (array_keys($action->when) as $field) {
+                if (! isset($fields[$field])) {
+                    throw new InvalidArgumentException("Action \"{$action->name}\" of {$name} depends on \"{$field}\", which is not one of its fields.");
+                }
+            }
+            // sendNow and send_now would be the same permission.
+            if (isset($keys[$action->key()])) {
+                throw new InvalidArgumentException("{$name} has two actions that come to \"{$action->key()}\".");
+            }
+            $keys[$action->key()] = true;
+        }
+        $public?->check($name, $fields);
+        foreach ($fields as $field) {
+            if ($field->from !== null && (! isset($fields[$field->from]) || ! in_array($fields[$field->from]->kind, ['string', 'text'], true))) {
+                throw new InvalidArgumentException("{$name}: \"{$field->name}\" is made from \"{$field->from}\", which has to be a string field of {$name}.");
+            }
+        }
+        if ($publish !== null && (! isset($fields[$publish]) || $fields[$publish]->kind !== 'datetime' || $fields[$publish]->required)) {
+            throw new InvalidArgumentException("{$name}: \"publish\" names the field that says when a record is published. It has to be an optional datetime: {$publish}:datetime?");
+        }
+        if ($blog !== null) {
+            if (! preg_match('#^/[a-z0-9][a-z0-9/-]*$#', $blog)) {
+                throw new InvalidArgumentException("{$name}: \"blog\" is where the blog is on the site, such as \"/blog\".");
+            }
+            if ($public?->read === null || $public->by === null) {
+                throw new InvalidArgumentException("{$name}: a blog reads its posts publicly, each by a unique field. Give it \"public\": { \"read\": { \"by\": \"slug\", \"fields\": […] } }.");
+            }
+        }
     }
 
     /** Build from a name and a `--fields` string: "name:string, price:money, status:enum(draft|live)?". */
-    public static function fromSpec(string $name, string $spec, ?string $icon = null, ?string $group = null): self
+    public static function fromSpec(string $name, string $spec, ?string $icon = null, ?string $group = null, string $idType = 'uuid'): self
     {
         $fields = [];
         foreach (array_filter(array_map('trim', self::splitSpec($spec))) as $token) {
@@ -47,11 +97,11 @@ final class Descriptor
             $fields[$field->name] = $field;
         }
 
-        return self::make(Naming::pascal($name), $fields, icon: $icon, group: $group);
+        return self::make(Naming::pascal($name), $fields, icon: $icon, group: $group, idType: $idType);
     }
 
     /** @param array<string, Field> $fields */
-    public static function make(string $name, array $fields, ?string $icon = null, ?string $group = null, ?string $titleField = null): self
+    public static function make(string $name, array $fields, ?string $icon = null, ?string $group = null, ?string $titleField = null, string $idType = 'uuid'): self
     {
         $plural = Naming::plural($name);
 
@@ -65,6 +115,7 @@ final class Descriptor
             $icon,
             $group,
             $titleField,
+            $idType,
         );
     }
 
@@ -77,6 +128,10 @@ final class Descriptor
             $fields[$key] = Field::fromArray($key, (array) $field);
         }
         $base = self::make($name, $fields);
+        $actions = [];
+        foreach ((array) ($data['actions'] ?? []) as $key => $action) {
+            $actions[(string) $key] = Action::fromArray((string) $key, (array) $action);
+        }
 
         return new self(
             $name,
@@ -88,6 +143,12 @@ final class Descriptor
             $data['icon'] ?? null,
             $data['group'] ?? null,
             $data['titleField'] ?? null,
+            (string) ($data['id'] ?? 'uuid'),
+            (bool) ($data['adopted'] ?? false),
+            $actions,
+            isset($data['public']) ? PublicAccess::fromArray((array) $data['public']) : null,
+            $data['publish'] ?? null,
+            $data['blog'] ?? null,
         );
     }
 
@@ -107,13 +168,20 @@ final class Descriptor
             '$schema' => 'https://nevela.dev/schema/resource.v1.json',
             'name' => $this->name,
             'table' => $this->table,
+            // Left out when they are what every descriptor written before them means.
+            'id' => $this->idType === 'uuid' ? null : $this->idType,
+            'adopted' => $this->adopted ?: null,
             'slug' => $this->slug,
             'label' => $this->label,
             'pluralLabel' => $this->pluralLabel,
             'icon' => $this->icon,
             'group' => $this->group,
             'titleField' => $this->titleField,
+            'publish' => $this->publish,
+            'blog' => $this->blog,
             'fields' => array_map(fn (Field $f) => $f->toArray(), $this->fields),
+            'actions' => $this->actions ? array_map(fn (Action $a) => $a->toArray(), $this->actions) : null,
+            'public' => $this->public?->toArray(),
         ], fn ($v) => $v !== null);
     }
 
@@ -137,6 +205,17 @@ final class Descriptor
         return 'id';
     }
 
+    /**
+     * This resource with only some of its fields: what a list of it is sorted, filtered
+     * and searched by when the list is the public one.
+     *
+     * @param  list<string>  $fields
+     */
+    public function only(array $fields): self
+    {
+        return new self($this->name, array_intersect_key($this->fields, array_flip($fields)), $this->table, $this->slug, $this->label, $this->pluralLabel, $this->icon, $this->group, null, $this->idType, $this->adopted);
+    }
+
     public function variable(): string
     {
         return Naming::camel($this->name);

package/template/laravel/src/Support/Fake.php

@@ -133,11 +133,25 @@ final class Fake
             'datetime' => $field->unique
                 ? gmdate('Y-m-d H:i:s', self::EPOCH + $number)
                 : date('Y-m-d H:i:s', time() - mt_rand(0, 365 * 86400)),
-            'text' => self::sentence(mt_rand(8, 24)).($field->unique ? " {$number}" : ''),
+            'text' => $field->isRich()
+                ? self::article($field->unique ? " {$number}" : '')
+                : self::sentence(mt_rand(8, 24)).($field->unique ? " {$number}" : ''),
             default => self::string($field, $number, $first, $last, $isPerson),
         };
     }
 
+    /** A few paragraphs with a heading and a list, so a seeded record reads like one somebody wrote. */
+    private static function article(string $suffix): string
+    {
+        $items = implode('', array_map(fn () => '<li>'.ucfirst(self::sentence(mt_rand(3, 6))).'</li>', range(1, 3)));
+
+        return '<p>'.self::sentence(mt_rand(14, 24)).'</p>'
+            .'<h2>'.rtrim(self::sentence(mt_rand(3, 5)), '.').$suffix.'</h2>'
+            .'<p>'.self::sentence(mt_rand(12, 20)).' <strong>'.rtrim(self::sentence(mt_rand(2, 4)), '.').'</strong>, '.lcfirst(self::sentence(mt_rand(6, 10))).'</p>'
+            ."<ul>{$items}</ul>"
+            .'<p>'.self::sentence(mt_rand(10, 18)).'</p>';
+    }
+
     private static function string(Field $field, int $number, string $first, string $last, bool $isPerson): string
     {
         $name = strtolower($field->name);

package/template/laravel/src/Support/Field.php

@@ -14,6 +14,7 @@ final class Field
 
     public const FORMATS = [
         'string' => ['email', 'url', 'tel', 'slug', 'color'],
+        'text' => ['rich'],
         'float' => ['money', 'percent', 'rating'],
         'int' => ['percent', 'rating'],
     ];
@@ -23,7 +24,7 @@ final class Field
 
     /** Shorthand types accepted by --fields, mapped to kind + format. */
     private const ALIASES = [
-        'string' => ['string', null], 'text' => ['text', null],
+        'string' => ['string', null], 'text' => ['text', null], 'richtext' => ['text', 'rich'],
         'email' => ['string', 'email'], 'url' => ['string', 'url'], 'tel' => ['string', 'tel'],
         'slug' => ['string', 'slug'], 'color' => ['string', 'color'],
         'int' => ['int', null], 'integer' => ['int', null],
@@ -40,6 +41,10 @@ final class Field
      * @param  string|null  $target  belongsTo: the resource this points at, e.g. "Category"
      * @param  list<string>  $accept  file: the categories it takes, e.g. ["image"]
      * @param  string|null  $profile  file: the image profile uploads are optimised with (config nevela.uploads.profiles)
+     * @param  int|null  $maxLength  string and text: the most characters it holds, where that isn't the usual 255 or 65,535
+     * @param  bool  $private  file: kept where the web server doesn't reach, and handed only to someone who may view the record
+     * @param  string|int|float|bool|null  $default  What the field is when a create leaves it out. Also the column's default.
+     * @param  string|null  $from  slug: the field it is made from when a create leaves it empty, e.g. "title"
      */
     public function __construct(
         public readonly string $name,
@@ -52,6 +57,10 @@ final class Field
         public readonly ?string $target = null,
         public readonly array $accept = [],
         public readonly ?string $profile = null,
+        public readonly ?int $maxLength = null,
+        public readonly bool $private = false,
+        public readonly string|int|float|bool|null $default = null,
+        public readonly ?string $from = null,
     ) {
         if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $name)) {
             throw new InvalidArgumentException("Field \"{$name}\" must be camelCase (e.g. publishedAt).");
@@ -65,6 +74,9 @@ final class Field
         if ($format !== null && ! in_array($format, self::FORMATS[$kind] ?? [], true)) {
             throw new InvalidArgumentException("Format \"{$format}\" is not valid for {$kind} field \"{$name}\".");
         }
+        if ($maxLength !== null && (! in_array($kind, ['string', 'text'], true) || $format === 'color' || $maxLength < 1)) {
+            throw new InvalidArgumentException("\"{$name}\" can't have a length of {$maxLength}: a length is a whole number of 1 or more, on a string or text field.");
+        }
         if ($kind === 'enum' && $options === []) {
             throw new InvalidArgumentException("Enum field \"{$name}\" needs values, e.g. {$name}:enum(draft|published).");
         }
@@ -81,6 +93,33 @@ final class Field
                 throw new InvalidArgumentException("A belongsTo field holds an id, so its name ends in \"Id\": {$name}Id.");
             }
         }
+        if ($default !== null) {
+            $fits = match ($kind) {
+                'string', 'text' => is_string($default) && ! ($kind === 'text' && $format === 'rich'),
+                'int' => is_int($default),
+                'float' => is_int($default) || is_float($default),
+                'boolean' => is_bool($default),
+                'enum' => is_string($default) && in_array($default, $options, true),
+                default => false,
+            };
+            if (! $fits) {
+                throw new InvalidArgumentException("The default of \"{$name}\" has to be a value the field could hold".($kind === 'enum' ? ': one of '.implode(', ', $options).'.' : (in_array($kind, ['string', 'text', 'int', 'float', 'boolean'], true) ? '.' : ", and a {$kind} field can't have one.")));
+            }
+            if ($unique) {
+                throw new InvalidArgumentException("\"{$name}\" is unique, so only one record could ever have its default.");
+            }
+        }
+        if ($from !== null) {
+            if ($kind !== 'string' || $format !== 'slug') {
+                throw new InvalidArgumentException("\"{$name}\" can't be made from another field: that is for a slug ({$name}:slug({$from})).");
+            }
+            if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $from) || $from === $name) {
+                throw new InvalidArgumentException("\"{$name}\" is made from a field of the same resource, named as it is there: {$name}:slug(title).");
+            }
+        }
+        if ($private && $kind !== 'file') {
+            throw new InvalidArgumentException("\"{$name}\" can't be private: that is for file fields. Who may see a record's other fields is its policy's to say.");
+        }
         if ($kind === 'file') {
             if ($accept === []) {
                 throw new InvalidArgumentException("File field \"{$name}\" needs what it accepts, e.g. {$name}:image or {$name}:file(pdf|image).");
@@ -103,15 +142,41 @@ final class Field
      * Parse one `name:type` token. Suffix `?` = optional (nullable), `!` = unique; both may be combined.
      *
      *   status:enum(draft|published)
+     *   excerpt:string(500)               a length other than the usual 255
+     *   body:richtext                     formatted text, kept as HTML that has been cleaned
      *   category:belongsTo(Category)      stored as categoryId
      *   image:image                       an optimised image; image:image(product) names a profile
      *   manual:file(pdf|document)         any other upload
+     *   cv:file(pdf|private)              one only those who may view the record can fetch
+     *   status:enum(pending|paid)=pending what it is when a create leaves it out
+     *   slug:slug(title)!                 made from the title when left empty
      *
      * Grit's and Flare's spellings are understood too: see normalise().
      */
     public static function parse(string $token): self
     {
         $written = trim($token);
+        // status:enum(pending|paid)=pending: what the field is when a create leaves it out.
+        $default = null;
+        if (($at = strpos($written, '=')) !== false) {
+            $default = trim(substr($written, $at + 1));
+            $written = rtrim(substr($written, 0, $at));
+        }
+        if ($default !== null) {
+            $field = self::parse($written);
+            $value = match ($field->kind) {
+                'int' => filter_var($default, FILTER_VALIDATE_INT) === false ? $default : (int) $default,
+                'float' => is_numeric($default) ? (float) $default : $default,
+                'boolean' => match (strtolower($default)) {
+                    'true', '1', 'yes' => true,
+                    'false', '0', 'no' => false,
+                    default => $default,
+                },
+                default => $default,
+            };
+
+            return self::fromArray($field->name, ['default' => $value] + $field->toArray());
+        }
         $token = self::normalise($written);
         if (! preg_match('/^([A-Za-z][A-Za-z0-9_]*):([A-Za-z_]+)(?:\(([^)]*)\))?([?!]{0,2})$/', $token, $m)) {
             throw new InvalidArgumentException("Invalid field \"{$written}\". Expected name:type, e.g. price:money, status:enum(draft|live)?, image:image or category:belongsTo(Category).");
@@ -135,14 +200,23 @@ final class Field
             return new self($name, 'file', null, $required, $unique, accept: ['image'], profile: $list[0] ?? null);
         }
         if ($type === 'file') {
-            return new self($name, 'file', null, $required, $unique, accept: $list ?: ['any']);
+            // cv:file(pdf|private): "private" among what it takes is how it is kept, not a kind of file.
+            $accept = array_values(array_diff($list, ['private']));
+
+            return new self($name, 'file', null, $required, $unique, accept: $accept ?: ['any'], private: count($accept) !== count($list));
         }
         if (! isset(self::ALIASES[$type])) {
             throw new InvalidArgumentException("Unknown type \"{$type}\" on \"{$name}\". Use one of: ".implode(', ', array_keys(self::ALIASES)).', enum(a|b), belongsTo(Resource), image, file(pdf|…).');
         }
         [$kind, $format] = self::ALIASES[$type];
+        // slug:slug(title)!: made from the title when a create leaves it empty.
+        if ($format === 'slug' && $args !== '' && ! ctype_digit($args)) {
+            return new self($name, $kind, $format, $required, $unique, from: Naming::camel($args));
+        }
+        // excerpt:string(500): a length of its own.
+        $maxLength = in_array($kind, ['string', 'text'], true) && $format !== 'color' && ctype_digit($args) ? (int) $args : null;
 
-        return new self($name, $kind, $format, $required, $unique);
+        return new self($name, $kind, $format, $required, $unique, maxLength: $maxLength);
     }
 
     /**
@@ -183,6 +257,10 @@ final class Field
             $data['target'] ?? null,
             array_values($data['accept'] ?? []),
             $data['profile'] ?? null,
+            isset($data['maxLength']) ? (int) $data['maxLength'] : null,
+            (bool) ($data['private'] ?? false),
+            $data['default'] ?? null,
+            $data['from'] ?? null,
         );
     }
 
@@ -196,6 +274,10 @@ final class Field
             'target' => $this->target,
             'accept' => $this->accept ?: null,
             'profile' => $this->profile,
+            'maxLength' => $this->maxLength,
+            'private' => $this->private ?: null,
+            'default' => $this->default,
+            'from' => $this->from,
             'required' => $this->required ? null : false,
             'unique' => $this->unique ?: null,
             'label' => $this->label,
@@ -219,6 +301,12 @@ final class Field
         return substr($this->name, 0, -2);
     }
 
+    /** Whether this is text with formatting: written in an editor, kept as HTML, cleaned on the way in and out. */
+    public function isRich(): bool
+    {
+        return $this->kind === 'text' && $this->format === 'rich';
+    }
+
     /** Whether this is a file field that takes images only, and so is optimised and shown as a picture. */
     public function isImage(): bool
     {

package/template/laravel/src/Support/Html.php

@@ -0,0 +1,185 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use DOMDocument;
+use DOMElement;
+use DOMNode;
+use DOMText;
+
+/**
+ * Rich text, made safe to keep and to show.
+ *
+ * What a rich text field receives is whatever was sent: the dashboard's editor, a script,
+ * a CSV file, a visitor's form. None of it is trusted. The HTML is parsed, and written
+ * out again from what was understood, keeping only the tags and attributes on a list
+ * (config: nevela.rich_text). A tag that isn't on it goes and its words stay; a tag whose
+ * contents are not words, such as a script, goes with them.
+ *
+ * The same is done when a record is read, so that HTML which reached the table some other
+ * way (a column adopted from an older app, a row written by hand) is never shown as it is.
+ */
+final class Html
+{
+    /** What the dashboard's editor can make. */
+    public const TAGS = ['p', 'br', 'strong', 'em', 's', 'a', 'h2', 'h3', 'ul', 'ol', 'li', 'blockquote'];
+
+    /** Attributes kept, by tag. A link keeps where it goes and nothing else. */
+    public const ATTRIBUTES = ['a' => ['href']];
+
+    /** Where a link may go. One with no scheme, such as /about, is the site's own and is kept. */
+    public const SCHEMES = ['http', 'https', 'mailto'];
+
+    /** Other spellings of the same thing, as browsers and word processors write them. */
+    private const SAME_AS = ['b' => 'strong', 'i' => 'em', 'strike' => 's', 'del' => 's'];
+
+    /** Removed with everything inside them: what they hold was never text. */
+    private const DROPPED = ['script', 'style', 'iframe', 'object', 'embed', 'noscript', 'template', 'svg', 'math', 'head', 'title', 'textarea', 'select', 'option', 'button', 'audio', 'video', 'canvas', 'applet', 'frame', 'frameset', 'link', 'meta', 'base'];
+
+    /** Tags that sit inside a line of text. Anything else stands on lines of its own. */
+    private const INLINE = ['a', 'strong', 'em', 's', 'b', 'i', 'u', 'strike', 'del', 'ins', 'span', 'code', 'sub', 'sup', 'small', 'mark', 'font', 'br', 'abbr', 'cite', 'q', 'label', 'time', 'img', 'kbd', 'var', 'samp', 'big', 'tt', 'wbr'];
+
+    private const EMPTY = ['br', 'hr', 'img'];
+
+    /**
+     * The HTML with only what the list allows, or an empty string when there is nothing
+     * in it to read: an editor that was opened and left sends `<p><br></p>`.
+     *
+     * @param  array{tags?: list<string>, attributes?: array<string, list<string>>, schemes?: list<string>}|null  $allow  Null for config('nevela.rich_text')
+     */
+    public static function clean(?string $html, ?array $allow = null): string
+    {
+        if ($html === null || trim($html) === '') {
+            return '';
+        }
+        $allow ??= function_exists('config') && function_exists('app') && app()->bound('config') ? (array) config('nevela.rich_text', []) : [];
+        $tags = array_map('strtolower', (array) ($allow['tags'] ?? self::TAGS));
+        $attributes = (array) ($allow['attributes'] ?? self::ATTRIBUTES);
+        $schemes = array_map('strtolower', (array) ($allow['schemes'] ?? self::SCHEMES));
+
+        $document = new DOMDocument;
+        $before = libxml_use_internal_errors(true);
+        // Characters outside ASCII go in as numbered entities: the parser would otherwise
+        // have to guess the encoding, and guesses Latin-1.
+        $document->loadHTML('<html><body>'.mb_encode_numericentity($html, [0x80, 0x10FFFF, 0, 0x1FFFFF], 'UTF-8').'</body></html>');
+        libxml_clear_errors();
+        libxml_use_internal_errors($before);
+
+        $body = $document->getElementsByTagName('body')->item(0);
+        if ($body === null) {
+            return '';
+        }
+        $out = self::top($body, $tags, $attributes, $schemes);
+        $words = trim(html_entity_decode(strip_tags($out), ENT_QUOTES | ENT_HTML5, 'UTF-8'), " \t\n\r\0\x0B\u{A0}");
+
+        return $words === '' && ! str_contains($out, '<img') ? '' : $out;
+    }
+
+    /**
+     * The top of the document, where everything is a paragraph, a heading, a list or a
+     * quote. Text and inline tags found loose there are gathered into paragraphs, so that
+     * plain text from a CSV file or a script is stored as what the editor would have made.
+     * A wrapper that isn't kept, such as a div, is looked into the same way.
+     *
+     * @param  list<string>  $tags
+     * @param  array<string, list<string>>  $attributes
+     * @param  list<string>  $schemes
+     */
+    private static function top(DOMNode $parent, array $tags, array $attributes, array $schemes): string
+    {
+        $paragraph = fn (string $inline) => trim($inline) === '' ? '' : (in_array('p', $tags, true) ? '<p>'.trim($inline).'</p>' : $inline);
+        $out = '';
+        $loose = '';
+        foreach ($parent->childNodes as $node) {
+            $name = $node instanceof DOMElement ? strtolower($node->nodeName) : '';
+            $name = self::SAME_AS[$name] ?? $name;
+            if ($name === '' || in_array($name, self::INLINE, true)) {
+                $loose .= self::write($node, $tags, $attributes, $schemes);
+
+                continue;
+            }
+            $out .= $paragraph($loose);
+            $loose = '';
+            $out .= in_array($name, $tags, true) || in_array($name, self::DROPPED, true)
+                ? self::write($node, $tags, $attributes, $schemes)
+                : self::top($node, $tags, $attributes, $schemes);
+        }
+
+        return $out.$paragraph($loose);
+    }
+
+    /** The words alone, on one line: what a table cell or a search result shows. */
+    public static function text(?string $html, int $limit = 0): string
+    {
+        $text = trim((string) preg_replace('/\s+/u', ' ', html_entity_decode(strip_tags((string) preg_replace('/<(br|\/p|\/h[1-6]|\/li|\/blockquote)\b[^>]*>/i', ' ', (string) $html)), ENT_QUOTES | ENT_HTML5, 'UTF-8')));
+
+        return $limit > 0 && mb_strlen($text) > $limit ? rtrim(mb_substr($text, 0, $limit - 1)).'…' : $text;
+    }
+
+
+    /**
+     * @param  list<string>  $tags
+     * @param  array<string, list<string>>  $attributes
+     * @param  list<string>  $schemes
+     */
+    private static function write(DOMNode $node, array $tags, array $attributes, array $schemes): string
+    {
+        if ($node instanceof DOMText) {
+            return htmlspecialchars($node->nodeValue ?? '', ENT_NOQUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');
+        }
+        if (! $node instanceof DOMElement) {
+            return ''; // a comment, a processing instruction
+        }
+        $name = strtolower($node->nodeName);
+        $name = self::SAME_AS[$name] ?? $name;
+        if (in_array($name, self::DROPPED, true)) {
+            return '';
+        }
+
+        $inner = '';
+        foreach ($node->childNodes as $child) {
+            $inner .= self::write($child, $tags, $attributes, $schemes);
+        }
+        if (! in_array($name, $tags, true)) {
+            // Not a tag to keep, but its words are. Where it stood on its own line, a space keeps them apart.
+            return in_array($name, self::INLINE, true) && $name !== 'br' ? $inner : $inner.' ';
+        }
+
+        $kept = '';
+        foreach ((array) ($attributes[$name] ?? []) as $attribute) {
+            $value = $node->getAttribute($attribute);
+            if ($value === '' || (in_array($attribute, ['href', 'src'], true) && ! self::safe($value, $schemes))) {
+                continue;
+            }
+            $kept .= ' '.$attribute.'="'.htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8').'"';
+        }
+        // A link that goes nowhere is its words.
+        if ($name === 'a' && $kept === '') {
+            return $inner;
+        }
+        // A tag with nothing in it is nothing. Browsers leave these behind: Chrome puts a
+        // list inside the paragraph it was started in, which leaves an empty paragraph
+        // before it once the two are told apart. (A blank line is <p><br></p>, and is kept.)
+        if (! in_array($name, self::EMPTY, true) && trim($inner) === '') {
+            return '';
+        }
+
+        return in_array($name, self::EMPTY, true) ? "<{$name}{$kept}>" : "<{$name}{$kept}>{$inner}</{$name}>";
+    }
+
+    /**
+     * Whether an address is one a link may have. A browser ignores spaces and control
+     * characters inside a scheme, so `java\tscript:` is read here the way it would be there.
+     *
+     * @param  list<string>  $schemes
+     */
+    private static function safe(string $address, array $schemes): bool
+    {
+        $address = (string) preg_replace('/[\x00-\x20\x7F]+/', '', $address);
+        if (! preg_match('/^([a-z][a-z0-9+.\-]*):/i', $address, $m)) {
+            return true; // no scheme: /about, #top, //example.com
+        }
+
+        return in_array(strtolower($m[1]), $schemes, true);
+    }
+}

package/template/laravel/src/Support/Key.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Str;
+
+/**
+ * Whether a string from an address could be a record's id at all.
+ *
+ * SQLite and MySQL answer "where id = 'nobody'" with no rows. Postgres checks the type
+ * first: an id column is a number or a UUID, 'nobody' is neither, and the query is an
+ * error, which reaches the visitor as a 500 where a 404 was meant. Inside a transaction
+ * it also aborts everything else in it. So an id is looked at before the database is
+ * asked, and one of the wrong shape is nobody's.
+ */
+final class Key
+{
+    /** A whole number that fits a bigint column. */
+    public static function isInt(mixed $id): bool
+    {
+        return is_scalar($id) && preg_match('/^[0-9]{1,18}$/', (string) $id) === 1;
+    }
+
+    public static function isUuid(mixed $id): bool
+    {
+        return is_string($id) && Str::isUuid($id);
+    }
+
+    /**
+     * Whether `$id` has the shape of this model's key: digits for a numbered key, and
+     * whatever a model with Laravel's UUID or ULID keys says is one of its own. A model
+     * with some other key of its own making is taken at its word.
+     *
+     * @param  Model|class-string<Model>  $model
+     */
+    public static function fits(Model|string $model, mixed $id): bool
+    {
+        $model = is_string($model) ? new $model : $model;
+        if (! is_scalar($id)) {
+            return false;
+        }
+        if (in_array($model->getKeyType(), ['int', 'integer'], true)) {
+            return self::isInt($id);
+        }
+
+        $traits = class_uses_recursive($model);
+
+        return match (true) {
+            isset($traits[HasUuids::class]) => Str::isUuid((string) $id),
+            isset($traits[HasUlids::class]) => Str::isUlid((string) $id),
+            default => true,
+        };
+    }
+}

package/template/laravel/src/Support/ListQuery.php

@@ -25,7 +25,17 @@ final class ListQuery
 
     public ?string $q = null;
 
-    /** @var list<array{field: string, column: string, value: string|int|float|bool|null}> */
+    /** The three things a record with a publish date can be. */
+    public const PUBLISHED = ['published', 'draft', 'scheduled'];
+
+    /** The filter that isn't a field: whether a record's address has been proved ("confirm"). */
+    public const CONFIRMED = 'confirmed';
+
+    /**
+     * A filter on the field a resource is published by carries `state` in place of a value.
+     *
+     * @var list<array{field: string, column: string, value: string|int|float|bool|null, state?: string, confirmed?: bool}>
+     */
     public array $filters = [];
 
     /** @param array<string, mixed> $params */
@@ -66,6 +76,24 @@ final class ListQuery
         foreach ($filters as $key => $value) {
             $param = "filter[{$key}]";
             $field = $resource->fields[$key] ?? null;
+            // filter[publishedAt]=draft: not a date to match, but which of the three it is.
+            if ($field !== null && $resource->publish === $key) {
+                $state = is_string($value) ? strtolower($value) : '';
+                in_array($state, self::PUBLISHED, true)
+                    ? $query->filters[] = ['field' => $key, 'column' => $field->column(), 'value' => null, 'state' => $state]
+                    : $query->issue($param, 'Must be one of: '.implode(', ', self::PUBLISHED).'.');
+
+                continue;
+            }
+            // filter[confirmed]=true: whether the address was proved, for a resource whose form asks.
+            if ($field === null && $key === self::CONFIRMED && $resource->public?->confirm !== null) {
+                $proved = is_array($value) ? null : filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+                $proved === null
+                    ? $query->issue($param, 'Must be true or false.')
+                    : $query->filters[] = ['field' => $key, 'column' => 'confirmed_at', 'value' => null, 'confirmed' => $proved];
+
+                continue;
+            }
             if ($field === null || ! $field->filterable()) {
                 $query->issue($param, "Can't filter by \"{$key}\".");