@orieljs/live 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,16 @@
+Oriel
+Copyright 2026 meeeet-dev and Oriel contributors
+
+This product includes software developed by the Oriel project
+(https://orieljs.vercel.app, https://github.com/orieljs).
+
+Oriel is licensed under the Apache License, Version 2.0 (see LICENSE).
+The Oriel name and logo are not covered by that license; see TRADEMARKS.md
+(https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).
+
+@orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
+voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -0,0 +1,265 @@
+# @orieljs/live
+
+Server-side Live components for Oriel: Livewire-style components written in TSX, with signed snapshots, actions, events and `Live.test()`. Live is part of `@orieljs/framework`, which every Oriel app already installs, and is re-exported from it. Its semantics follow Livewire 3. In an app, import it from `@orieljs/framework` only: `@orieljs/live` is also published on its own, but a separate copy doesn't share the framework's per-request state.
+
+```bash
+npm install @orieljs/framework
+```
+
+```tsx title="app/Live/Counter.tsx"
+import { Component } from '@orieljs/framework'
+
+export default class Counter extends Component {
+  count = 0
+
+  increment() {
+    this.count++
+  }
+
+  render() {
+    return <button o:click="increment">{this.count}</button>
+  }
+}
+```
+
+```ts title="routes/web.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component { render() { return <p /> } }
+// ---cut---
+import { Route } from '@orieljs/framework'
+import Counter from '../app/Live/Counter'
+
+Route.get('/counter', Counter)
+```
+
+Embed a component in any view with `<Live component={Counter} />`. In the browser, components are driven by `@orieljs/live-client`. Public fields are a component's state and its public methods are actions. `mount()` and `render()` may be async (`const user = await request().user<User>()`), and `await this.validate(rules)` returns the validated data, typed from the rules.
+
+## Typed actions
+
+`this.$action(method, ...arguments)` writes an action for an `o:` directive, typed against the method:
+
+```tsx title="app/Live/Drafts.tsx"
+import { Component } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class Drafts extends Component {
+  async publish(id: number) {
+    const post = await Post.findOrFail(id)
+    post.published_at = new Date()
+    await post.save()
+  }
+
+  async render() {
+    const drafts = await Post.whereNull('published_at').get()
+    return (
+      <ul>
+        {drafts.map((post) => (
+          <li>
+            {post.title}
+            <button type="button" o:click={this.$action(this.publish, post.id)}>Publish</button>
+          </li>
+        ))}
+      </ul>
+    )
+  }
+}
+```
+
+For post 5 this renders `o:click="publish(5)"`, and since `publish(id: number)` takes a number,
+`this.$action(this.publish, String(post.id))` is a type error. The arguments are written as JSON, so pass ids and
+plain values (strings, numbers, booleans, `null`, arrays and plain objects): a model arrives as its attributes and a
+date as its ISO string, so pass `post.id`, not `post`. The action contains double quotes, so use it as a TSX attribute
+value, which escapes them, not inside an HTML string you write by hand. Rendering throws when the method isn't one of
+the component's actions (a hook, or a `#private` or `@Locked` method). The types check what your pages send; a crafted
+request can still send anything, so an action checks what it is given, as a controller does.
+
+## Confirming an action
+
+`o:confirm` asks before an action runs, as Livewire's `wire:confirm`:
+
+```tsx
+declare const tag: { id: number }
+// ---cut---
+<button type="button" class="btn btn-danger" o:click={`delete(${tag.id})`} o:confirm="Delete this tag?">
+  Delete
+</button>
+```
+
+The browser's confirm dialog shows the message (an empty `o:confirm` asks "Are you sure?", and `\n` is a line break),
+and the action runs only when it is accepted. `o:confirm-prompt="Type DELETE to confirm|DELETE"` (`o:confirm.prompt`
+in plain HTML) asks with a prompt instead, and runs the action only when the answer is exactly the text after the `|`.
+It works on any element with an `o:` action: `o:click`, `o:submit` on a form, `o:keydown-enter`, and the others. A
+dismissed dialog stops the event, so the actions of the elements around it don't run either. With `-once`, a dismissed
+dialog doesn't use the action up. `o:confirm` guards the actions of the element it sits on: on a form, put it on the
+`<form>` with the `o:submit`. A button inside a form with its own `o:click` needs `type="button"` or `-prevent`
+(`o:click-prevent`), or the browser still submits the form when the dialog is dismissed.
+
+## Pagination
+
+```tsx title="app/Live/Posts.tsx"
+import { Component, Pagination, WithPagination } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class Posts extends WithPagination(Component) {
+  search = ''
+
+  async updatedSearch() {
+    await this.resetPage()
+  }
+
+  async render() {
+    const posts = await Post.whereLike('title', `%${this.search}%`).latest().paginate(10)
+    return (
+      <div>
+        <input o:model-live="search" aria-label="Search" />
+        {posts.items().map((post) => <p>{post.title}</p>)}
+        <Pagination paginator={posts} class="flex gap-2" />
+      </div>
+    )
+  }
+}
+```
+
+`paginate()` in the component (in `render()`, in `mount()`, in actions and the update hooks, or in a `@Computed`
+getter any of them reads) shows the component's `page`, and its links are built on the page's URL. The actions
+`nextPage`, `previousPage`, `gotoPage(n)`, `setPage(n)` and `resetPage` move it (they are async, so await them in your
+own methods); `<Pagination>` renders them as buttons with the kits' `btn` classes. The page starts at 1 and isn't kept
+in the address bar.
+
+## File uploads
+
+```tsx title="app/Live/ProfilePhoto.tsx"
+import { Component, TemporaryUploadedFile, WithFileUploads } from '@orieljs/framework'
+
+export default class ProfilePhoto extends WithFileUploads(Component) {
+  photo: TemporaryUploadedFile | null = null
+
+  async save() {
+    const { photo } = await this.validate({ photo: 'required|image|max:1024' })
+    await photo.store('photos')
+    this.reset('photo')
+  }
+
+  render() {
+    return (
+      <form o:submit="save">
+        <input type="file" o:model="photo" />
+        {this.photo?.isPreviewable() ? <img src={this.photo.temporaryUrl()} alt="Preview" /> : null}
+        <button type="submit">Save</button>
+      </form>
+    )
+  }
+}
+```
+
+In a `WithFileUploads` component, `o:model` on a file input uploads the picked file at once, to a temporary
+directory, and sets the property to a `TemporaryUploadedFile` (an array of them with `multiple`). Validate it with the
+file rules, preview it with `temporaryUrl()` (a signed link, for images, audio and video), and `store()` it. In tests,
+`Live.test()`'s `set('photo', file)` uploads a file the same way. Every upload must also pass
+`live.temporary_file_upload.rules`, which allow 12 MB (`max:12288`), but a request body larger than
+`http.max_body_size` (8 MB, for every request) gets a 413: raise it in `config/http.ts` to accept files up to the
+rule's size.
+
+## Lazy components
+
+```tsx title="app/Live/PostCount.tsx"
+import { Component } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class PostCount extends Component {
+  static override lazy = true
+  count = 0
+
+  async mount() {
+    this.count = await Post.count()
+  }
+
+  placeholder() {
+    return <p>Counting posts…</p>
+  }
+
+  render() {
+    return <p>{this.count} posts</p>
+  }
+}
+```
+
+With `static override lazy = true`, each `<Live component={PostCount} />` (and the full page) renders the
+placeholder first and mounts the component once it scrolls into view. `lazy` on one embed makes that embed lazy,
+`lazy="on-load"` mounts it as soon as the page loads, and `lazy={false}` turns `static lazy` off. Without
+`placeholder()`, the placeholder is the `live.lazy_placeholder` view, else an empty `<div>`; it needs the same root
+element as `render()`.
+
+## Navigating
+
+`<a href="/posts" o:navigate>` shows the next page without a full reload: Live fetches it (from `mousedown`, or on
+hover with `o:navigate-hover`), merges its `<head>`, swaps the `<body>` and starts the new page's components.
+`this.redirect(url, { navigate: true })` does the same from an action. The new page's scripts run as on a full load,
+except a `<head>` script the page already has, and a `<body>` script marked `data-navigate-once` that an earlier page
+already ran.
+
+## Middleware on updates
+
+Each update re-runs the `auth`, `verified`, `guest` and `can` middleware of the route that rendered the page
+(Livewire's persistent middleware), with that route's parameters bound again, so `can:update,post` sees the post. A
+signed-out tab gets a 401 and a user who lost the ability a 403, before the component's actions run. On a page behind
+one of these middleware, a model deleted since the page rendered gets a 404 too; a page with none binds nothing on
+updates. The list is `live.persistent_middleware`, which a `config/live.ts` of your own can set.
+
+## Flash data in updates
+
+A status an action flashes (`session().flash('status', 'Saved.')`) shows in that update's response only, unless the
+action redirects or navigates: then it is there on the next page. Component state is unaffected.
+
+## Status messages announced again
+
+Screen readers announce a status region (`role="status"`) when its text changes. When an action brings the same
+message again ("Saved" after a second save), the page doesn't change and nothing is announced. Add `o:announce` to the
+region and Live takes the message out and puts it back a moment later, so it is announced again:
+
+```tsx title="app/Live/Settings.tsx"
+import { Component } from '@orieljs/framework'
+
+export default class Settings extends Component {
+  name = ''
+  #saved = false
+
+  save() {
+    this.#saved = true
+  }
+
+  render() {
+    return (
+      <form o:submit="save">
+        <input o:model="name" aria-label="Name" />
+        <button type="submit">Save</button>
+        <p role="status" o:announce>
+          {this.#saved ? 'Saved' : ''}
+        </p>
+      </form>
+    )
+  }
+}
+```
+
+Only actions do this, and an `o:poll` that calls a method counts as one: an update that only syncs `o:model` values,
+refreshes or delivers an event leaves the region alone. Keep a status for one response (a `#private` field, or a
+flashed `status`), so that any other update clears it; a status kept in a public property is announced again by every
+action until it changes, which in a polled component is every tick. Keep an `o:announce` region to text: its children
+are taken out for 100 ms, so a button or input inside it would lose focus.
+
+## Known limitations
+
+- A DOM event whose name contains `-` can't be an `o:<event>` action, because `-` (and `.`) separate the modifiers (for example `o:model-live`).
+- `temporaryUrl()` previews don't answer range requests, which Safari needs to play a `<video>`.
+
+Documentation: https://orieljs.vercel.app/docs/live
+
+Status: early alpha. APIs will change.
+
+## License
+
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
+
+Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.