@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/display-blocks/s3download.md

@@ -0,0 +1,240 @@
+# S3Download
+
+__Deprecated__ — use the provider-neutral <a href="/Download">Download</a> block with `downloadPolicyRequestId` instead. S3Download remains as an alias so existing apps keep working. Download files from AWS S3. Requires an AwsS3Bucket connection and an AwsS3PresignedGetObject request. The s3GetPolicyRequestId property must reference the request id. If files were uploaded with S3Upload, its fileList value can be mapped directly to this block.
+
+> The S3Download block requires an AwsS3Bucket connection and an AwsS3PresignedGetObject request. The examples below show configuration structure but will not download files without a configured connection.
+
+```yaml
+- id: basic_download
+  type: S3Download
+  properties:
+    s3GetPolicyRequestId: download_file
+    fileList:
+      - key: report.pdf
+        type: application/pdf
+        name: report.pdf
+      - key: photo.jpg
+        type: image/jpeg
+        name: photo.jpg
+```
+
+```yaml
+- id: single_file
+  type: S3Download
+  properties:
+    s3GetPolicyRequestId: download_file
+    fileList:
+      - key: invoice_2026_001.pdf
+        type: application/pdf
+        name: invoice_2026_001.pdf
+```
+
+```yaml
+- id: multi_type
+  type: S3Download
+  properties:
+    s3GetPolicyRequestId: download_file
+    fileList:
+      - key: documents/contract.pdf
+        type: application/pdf
+        name: contract.pdf
+      - key: images/logo.png
+        type: image/png
+        name: logo.png
+      - key: data/export.csv
+        type: text/csv
+        name: export.csv
+      - key: archives/backup.zip
+        type: application/zip
+        name: backup.zip
+```
+
+```yaml
+- id: styled_download
+  type: S3Download
+  style:
+    .element:
+      background: "#f6ffed"
+      border: 1px solid
+      borderRadius: 8
+      padding: 12
+  properties:
+    s3GetPolicyRequestId: download_file
+    fileList:
+      - key: report.pdf
+        type: application/pdf
+        name: Quarterly Report.pdf
+      - key: summary.pdf
+        type: application/pdf
+        name: Executive Summary.pdf
+```
+
+```yaml
+- id: themed_download
+  type: S3Download
+  properties:
+    s3GetPolicyRequestId: download_file
+    theme:
+      actionsColor: "#f5222d"
+      controlItemBgHover: "#f9f0ff"
+      colorIcon: "#f5222d"
+      fontSize: 18
+    fileList:
+      - key: contracts/nda.pdf
+        type: application/pdf
+        name: Non-Disclosure Agreement.pdf
+      - key: contracts/sla.pdf
+        type: application/pdf
+        name: Service Level Agreement.pdf
+      - key: contracts/msa.pdf
+        type: application/pdf
+        name: Master Services Agreement.pdf
+```
+
+Full page config with connection, request, and S3Download block:
+```yaml
+# lowdefy.yaml
+connections:
+  - id: project_files
+    type: AwsS3Bucket
+    properties:
+      accessKeyId:
+        _secret: FILES_S3_ACCESS_KEY_ID
+      secretAccessKey:
+        _secret: FILES_S3_SECRET_ACCESS_KEY
+      region: us-east-1
+      bucket:
+        _secret: FILES_S3_BUCKET
+
+# page config
+id: document_portal
+type: PageSiderMenu
+blocks:
+  - id: documents_card
+    type: Card
+    properties:
+      title: Project Documents
+    blocks:
+      - id: download_files
+        type: S3Download
+        properties:
+          s3GetPolicyRequestId: download_file
+          fileList:
+            - key: projects/alpha/proposal.pdf
+              type: application/pdf
+              name: Project Alpha - Proposal.pdf
+            - key: projects/alpha/budget.xlsx
+              type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+              name: Project Alpha - Budget.xlsx
+        requests:
+          - id: download_file
+            type: AwsS3PresignedGetObject
+            connectionId: project_files
+            payload:
+              key:
+                _event: file.key
+              type:
+                _event: file.type
+            properties:
+              key:
+                _payload: key
+              responseContentType:
+                _payload: type
+```
+
+Upload and download files on the same page by mapping the S3Upload fileList to S3Download:
+```yaml
+# lowdefy.yaml
+connections:
+  - id: attachments
+    type: AwsS3Bucket
+    properties:
+      accessKeyId:
+        _secret: FILES_S3_ACCESS_KEY_ID
+      secretAccessKey:
+        _secret: FILES_S3_SECRET_ACCESS_KEY
+      region: us-east-1
+      bucket:
+        _secret: FILES_S3_BUCKET
+      write: true
+
+# page config
+id: file_management
+type: PageSiderMenu
+blocks:
+  - id: upload_card
+    type: Card
+    properties:
+      title: Upload Files
+    blocks:
+      - id: upload_files
+        type: S3Upload
+        properties:
+          s3PutPolicyRequestId: upload_policy
+        requests:
+          - id: upload_policy
+            type: AwsS3PresignedPutObject
+            connectionId: attachments
+            payload:
+              filename:
+                _event: filename
+            properties:
+              key:
+                _payload: filename
+  - id: download_card
+    type: Card
+    properties:
+      title: Download Uploaded Files
+    blocks:
+      - id: download_files
+        type: S3Download
+        properties:
+          s3GetPolicyRequestId: download_policy
+          # Map fileList directly from S3Upload state
+          fileList:
+            _state: upload_files
+        requests:
+          - id: download_policy
+            type: AwsS3PresignedGetObject
+            connectionId: attachments
+            payload:
+              key:
+                _event: file.key
+              type:
+                _event: file.type
+            properties:
+              key:
+                _payload: key
+              responseContentType:
+                _payload: type
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `fileList` | array | - | List of files to be downloaded. If files were uploaded using an S3Upload block, the fileList value can just be mapped to this field. |
+| `fileList.$.key` | string | - | S3 file key. |
+| `fileList.$.lastModified` | string | - | File last modified date. |
+| `fileList.$.name` | string | - | File name. |
+| `fileList.$.size` | number | - | File size in bytes. |
+| `fileList.$.type` | string | - | File MIME type. |
+| `s3GetPolicyRequestId` | string | - | Id of a request of type AwsS3PresignedGetObject that defines which S3 bucket and file to download. |
+| `showRemoveIcon` | boolean | `false` | Show a remove (×) icon next to each file in the list. Clicking it fires the `onRemove` event; the file is not removed from `fileList` automatically — the action handler is responsible. |
+| `theme` | object | - | Antd design token overrides for this block. See [antd design tokens](https://ant.design/components/upload#design-token). See [Ant Design upload tokens](https://ant.design/components/upload#design-token). |
+| `theme.actionsColor` | string | - | Color of action icons (download, preview, remove). |
+| `theme.pictureCardSize` | number | - | Size of list items in card type (affects both picture-card and picture-circle). |
+| `theme.controlItemBgHover` | string | - | Background color of file item on hover. |
+| `theme.colorIcon` | string | - | Color of file icons. |
+| `theme.fontSize` | number | - | Font size of file name text. |
+| `theme.borderRadiusSM` | number | - | Border radius of file list items. |
+
+| Event | Event Data | Description |
+| --- | --- | --- |
+| `onChange` | \- | Triggered when the upload state is changing. |
+| `onRemove` | `{ file }` | Triggered when a file remove icon is clicked. The file is NOT removed automatically — the handler is responsible for updating `fileList` (e.g. via `SetState`). |
+
+| Key | Target |
+| --- | --- |
+| `/block` | Outer block wrapper (always available). |
+| `/element` | The S3Download element. |
+
+No slots defined.

package/content/display-blocks/search.md

@@ -0,0 +1,360 @@
+# Search
+
+A full-text search command palette (Cmd+K / Ctrl+K) with keyboard navigation, result highlighting, and grouped results. Uses [MiniSearch](https://lucaong.github.io/minisearch/) for the search engine and antd Modal for the overlay. Two ways to provide data: pre-built index file via `indexUrl` (generated at build time, best for static content), or runtime `documents` array (indexed client-side, good for dynamic content). See the guide and examples below.
+
+## Generating a Search Index
+
+The Search block supports two data sources. For most apps, a **pre-built index file** is the best approach — it's generated once at build time and loaded on-demand when the user opens the search modal.
+
+### Option 1: Pre-built index file (recommended)
+
+Create a JavaScript transformer that runs during `lowdefy build`. It receives all resolved pages, extracts searchable text, builds a [MiniSearch](https://lucaong.github.io/minisearch/) index, and writes it to `public/search-index.json`.
+
+**Step 1 — Write the transformer:**
+
+```javascript
+// templates/buildSearchIndex.js
+import MiniSearch from 'minisearch';
+import fs from 'fs';
+import path, { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function buildSearchIndex(pages) {
+  // Extract searchable content from each page
+  const documents = pages.filter(Boolean).map((page) => ({
+    id: page.id,
+    pageId: page.id,
+    title: page.properties?.title ?? page.id,
+    section: 'Docs', // or derive from menus
+    description: '', // extract from page content as needed
+  }));
+
+  const miniSearch = new MiniSearch({
+    fields: ['title', 'description'],
+    storeFields: ['title', 'pageId', 'section'],
+  });
+  miniSearch.addAll(documents);
+
+  // The index JSON format the Search block expects
+  const index = {
+    engine: 'minisearch',
+    version: 1,
+    options: {
+      fields: ['title', 'description'],
+      storeFields: ['title', 'pageId', 'section'],
+      idField: 'id',
+    },
+    searchDefaults: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true,
+    },
+    resultDefaults: {
+      title: 'title',
+      description: 'description',
+      pageId: 'pageId',
+    },
+    data: JSON.parse(JSON.stringify(miniSearch)),
+  };
+
+  const dir = path.join(dirname(fileURLToPath(import.meta.url)), '../public');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'search-index.json'), JSON.stringify(index));
+}
+
+export default buildSearchIndex;
+```
+
+**Step 2 — Wire it into lowdefy.yaml:**
+
+```yaml
+# lowdefy.yaml
+pages:
+  _ref:
+    path: pages.yaml
+    transformer: templates/buildSearchIndex.js
+```
+
+The transformer runs during every build. The output file (`public/search-index.json`) is served as a static asset and fetched by the Search block when the modal opens.
+
+**Step 3 — Add the Search block:**
+
+```yaml
+- id: site_search
+  type: Search
+  properties:
+    indexUrl: /search-index.json
+  events:
+    onSelect:
+      - id: navigate
+        type: Link
+        params:
+          pageId:
+            _event: pageId
+```
+
+### Option 2: Runtime documents (no build step)
+
+For small datasets or dynamic content (e.g., from a request), pass documents directly. The block indexes them client-side:
+
+```yaml
+- id: feature_search
+  type: Search
+  properties:
+    documents:
+      - id: users
+        title: User Management
+        body: Create, edit, and deactivate user accounts.
+        category: Admin
+      - id: billing
+        title: Billing
+        body: View invoices and update payment methods.
+        category: Finance
+    fields: [title, body]
+    storeFields: [title, category, id]
+    searchOptions:
+      boost:
+        title: 2
+      fuzzy: 0.2
+    result:
+      title: title
+      description: body
+      category: category
+```
+
+You can also load documents from a request and pass them via state:
+
+```yaml
+properties:
+  documents:
+    _state: searchDocuments
+  fields: [title, body]
+  storeFields: [title, id]
+```
+
+### Index JSON format
+
+The `indexUrl` JSON file has this structure:
+
+| Key              | Type     | Description                                                                                  |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `engine`         | `string` | Always `"minisearch"`                                                                        |
+| `version`        | `number` | Schema version (currently `1`)                                                               |
+| `options`        | `object` | MiniSearch constructor options (`fields`, `storeFields`, `idField`)                          |
+| `searchDefaults` | `object` | Default search options (`boost`, `fuzzy`, `prefix`, `combineWith`)                           |
+| `resultDefaults` | `object` | Maps index fields to result UI (`title`, `description`, `category`, `pageId`, `url`, `icon`) |
+| `groups`         | `array`  | Result grouping definitions (`label`, `match`, `icon`)                                       |
+| `data`           | `object` | Serialized MiniSearch index (from `JSON.parse(JSON.stringify(miniSearch))`)                  |
+
+See the [MiniSearch API docs](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html) for all available field and search options.
+
+```yaml
+- id: example_search_prebuilt
+  type: Search
+  properties:
+    indexUrl: /search-index.json
+    placeholder: Search pages...
+    result:
+      title: title
+      description: snippet
+      category: section
+      pageId: pageId
+    groups:
+      - label: Concepts
+        match:
+          section: Concepts
+        icon: AiOutlineBulb
+      - label: Blocks
+        match:
+          section: Blocks
+        icon: AiOutlineLayout
+  events:
+    onSelect:
+      - id: navigate
+        type: Link
+        params:
+          pageId:
+            _event: pageId
+```
+
+```yaml
+- id: example_search_runtime
+  type: Search
+  properties:
+    documents:
+      - id: users
+        title: User Management
+        body: Create, edit, and deactivate user accounts. Assign roles and permissions.
+        category: Admin
+      - id: billing
+        title: Billing & Invoices
+        body: View invoices, update payment methods, and download receipts.
+        category: Finance
+      - id: reports
+        title: Analytics Reports
+        body: Dashboard with charts for revenue, signups, and engagement metrics.
+        category: Analytics
+      - id: settings
+        title: App Settings
+        body: Configure notifications, theme, language, and integration API keys.
+        category: Admin
+      - id: api-keys
+        title: API Keys
+        body: Generate and revoke API keys for third-party integrations.
+        category: Admin
+    fields:
+      - title
+      - body
+    storeFields:
+      - title
+      - category
+      - id
+    searchOptions:
+      boost:
+        title: 2
+      fuzzy: 0.2
+    result:
+      title: title
+      description: body
+      category: category
+    groups:
+      - label: Admin
+        match:
+          category: Admin
+        icon: AiOutlineSetting
+      - label: Finance
+        match:
+          category: Finance
+        icon: AiOutlineDollar
+      - label: Analytics
+        match:
+          category: Analytics
+        icon: AiOutlineBarChart
+    placeholder: Search features...
+    label: Find
+    shortcut: mod+k
+  events:
+    onSelect:
+      - id: show_result
+        type: DisplayMessage
+        params:
+          content:
+            _string.concat:
+              - "Selected: "
+              - _event: title
+```
+
+```yaml
+- id: example_search_custom_shortcut
+  type: Search
+  properties:
+    indexUrl: /search-index.json
+    shortcut: mod+j
+    label: Quick Find
+    placeholder: Quick find...
+  events:
+    onSelect:
+      - id: navigate
+        type: Link
+        params:
+          pageId:
+            _event: pageId
+```
+
+```yaml
+- id: example_search_analytics
+  type: Search
+  properties:
+    indexUrl: /search-index.json
+  events:
+    onSearch:
+      - id: track_search
+        type: DisplayMessage
+        params:
+          content:
+            _string.concat:
+              - 'Search: "'
+              - _event: value
+              - '" ('
+              - _event: resultCount
+              - " results)"
+    onSelect:
+      - id: track_click
+        type: DisplayMessage
+        params:
+          content:
+            _string.concat:
+              - Clicked "
+              - _event: title
+              - '" for query "'
+              - _event: query
+              - '"'
+      - id: navigate
+        type: Link
+        params:
+          pageId:
+            _event: pageId
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `indexUrl` | string \| array | - | URL or array of URLs to pre-built search index JSON files. |
+| `documents` | array | - | Array of document objects for client-side indexing. |
+| `fields` | array | - | Fields to index. Required when using documents, optional for indexUrl. |
+| `storeFields` | array | - | Fields to store in the index and return in results. |
+| `searchOptions` | object | - | MiniSearch search options. |
+| `searchOptions.boost` | object | - | Field boost factors for relevance scoring. |
+| `searchOptions.fuzzy` | number | - | Fuzzy matching tolerance as a fraction of term length (0 to 1). |
+| `searchOptions.prefix` | boolean | `true` | Enable prefix matching. |
+| `searchOptions.combineWith` | string | `"OR"` | How to combine search terms. Enum: `OR`, `AND`. |
+| `label` | string | `"Search"` | Trigger button text. |
+| `icon` | string \| object | - | Trigger button icon name or Icon block properties. |
+| `showShortcut` | boolean | `true` | Show keyboard shortcut badge on the trigger button. |
+| `placeholder` | string | `"Search..."` | Search input placeholder text. |
+| `shortcut` | string | `"mod+k"` | Keyboard shortcut to open the modal. Renders a shortcut badge on the trigger button (see showShortcut). Use "mod" for Cmd on Mac, Ctrl elsewhere. |
+| `width` | number | `640` | Modal width in pixels. |
+| `maxResults` | number | `20` | Maximum number of results displayed. |
+| `result` | object | - | Maps index fields to result UI slots. |
+| `result.title` | string | `"title"` | Field name for result title. |
+| `result.description` | string | - | Field name for result description/snippet. |
+| `result.category` | string | - | Field name for result grouping category. |
+| `result.icon` | string | - | Field name for result icon name. |
+| `result.pageId` | string | - | Field name for Lowdefy page navigation. |
+| `result.url` | string | - | Field name for external URL navigation. |
+| `groups` | array | - | Result grouping definitions. |
+| `groups.$.label` | string | - | Group display label. |
+| `groups.$.match` | object | - | Field/value pairs to match results to this group. |
+| `groups.$.icon` | string | - | Icon for the group header. |
+| `noResultsMessage` | string | `"No results found."` | Message shown when no results match. |
+| `highlightMatches` | boolean | `true` | Highlight matched terms in results. |
+| `recentSearches` | boolean | `true` | Show recent searches when input is empty. |
+| `recentSearchesKey` | string | `"search"` | localStorage key prefix for recent searches. |
+| `recentSearchesCount` | number | `5` | Maximum number of recent searches stored. |
+| `theme` | object | - | Antd design token overrides for this block. See [antd design tokens](https://ant.design/components/overview#design-token). |
+
+| Event | Event Data | Description |
+| --- | --- | --- |
+| `onSelect` | `{ query, resultCount }` | Trigger actions when a search result is selected. Result item stored fields are spread into the event object. |
+| `onSearch` | `{ value, resultCount }` | Trigger actions when the search query changes. |
+| `onOpen` | \- | Trigger actions when the search modal opens. |
+| `onClose` | \- | Trigger actions when the search modal closes. |
+
+| Key | Target |
+| --- | --- |
+| `/block` | Outer block wrapper (always available). |
+| `/element` | The search trigger button and modal root. |
+| `/trigger` | The trigger button. |
+| `/triggerBadge` | The keyboard shortcut badge on the trigger. |
+| `/modal` | The antd Modal container. |
+| `/input` | The search input field. |
+| `/results` | The scrollable results list. |
+| `/group` | A result group container. |
+| `/groupHeading` | A group heading label. |
+| `/item` | A result item row. |
+| `/itemIcon` | The icon in a result item. |
+| `/itemTitle` | The title in a result item. |
+| `/itemDescription` | The description/snippet in a result item. |
+| `/highlight` | Highlighted match text (<mark> elements). |
+| `/empty` | The empty state message. |
+
+No slots defined.