@hrbolek/uoisfrontend-template 0.6.0

package/src/_Template/Vectors/TemplateVectorsAttribute.jsx

@@ -0,0 +1,326 @@
+import { useEffect } from "react";
+import { Col } from "react-bootstrap";
+import { useAsyncAction, createAsyncGraphQLAction, processVectorAttributeFromGraphQLResult, createQueryStrLazy } from "@hrbolek/uoisfrontend-gql-shared"
+import { ErrorHandler, InfiniteScroll, LoadingSpinner } from "@hrbolek/uoisfrontend-shared"
+
+
+/**
+ * Inserts a VectorGQLModel item into a template’s vectors array and dispatches an update.
+ *
+ * @param {Object} template - The current template object containing a `vectors` array.
+ * @param {Object} vectorItem - The item to insert; must have `__typename === "VectorGQLModel"`.
+ * @param {Function} dispatch - Redux dispatch function (or similar) to call the update action.
+ */
+const followUpTemplateVectorItemInsert = (template, vectorItem, dispatch) => {
+    const { __typename } = vectorItem;
+    if (__typename === "VectorGQLModel") {
+        const { vectors, ...others } = template;
+        const newTemplateVectorItems = [...vectors, vectorItem];
+        const newTemplate = { ...others, vectors: newTemplateVectorItems };
+        dispatch(ItemActions.item_update(newTemplate));
+    }
+};
+
+/**
+ * Replaces an existing VectorGQLModel item in a template’s vectors array and dispatches an update.
+ *
+ * @param {Object} template - The current template object containing a `vectors` array.
+ * @param {Object} vectorItem - The updated item; must have `__typename === "VectorGQLModel"` and an `id` field matching an existing item.
+ * @param {Function} dispatch - Redux dispatch function (or similar) to call the update action.
+ */
+const followUpTemplateVectorItemUpdate = (template, vectorItem, dispatch) => {
+    const { __typename } = vectorItem;
+    if (__typename === "VectorGQLModel") {
+        const { vectors, ...others } = template;
+        const newTemplateVectorItems = vectors.map(item =>
+            item.id === vectorItem.id ? vectorItem : item
+        );
+        const newTemplate = { ...others, vectors: newTemplateVectorItems };
+        dispatch(ItemActions.item_update(newTemplate));
+    }
+};
+
+/**
+ * Removes a VectorGQLModel item from a template’s vectors array by its `id` and dispatches an update.
+ *
+ * @param {Object} template - The current template object containing a `vectors` array.
+ * @param {Object} vectorItem - The item to delete; must have `__typename === "VectorGQLModel"` and an `id` field.
+ * @param {Function} dispatch - Redux dispatch function (or similar) to call the update action.
+ */
+const followUpTemplateVectorItemDelete = (template, vectorItem, dispatch) => {
+    const { __typename } = vectorItem;
+    if (__typename === "VectorGQLModel") {
+        const { vectors, ...others } = template;
+        const newTemplateVectorItems = vectors.filter(
+            item => item.id !== vectorItem.id
+        );
+        const newTemplate = { ...others, vectors: newTemplateVectorItems };
+        dispatch(ItemActions.item_update(newTemplate));
+    }
+};
+
+const TemplateVectorsAttributeQuery = `
+query TemplateQueryRead($id: UUID!, $where: VectorInputFilter, $skip: Int, $limit: Int) {
+    result: templateById(id: $id) {
+        __typename
+        id
+        vectors(skip: $skip, limit: $limit, where: $where) {
+            __typename
+            id
+            # ...VectorMedium
+        }
+    }
+}
+`
+
+const TemplateVectorsAttributeAsyncAction = createAsyncGraphQLAction(
+    createQueryStrLazy(TemplateVectorsAttributeQuery,
+        //VectorMediumFragment
+    ),
+    processVectorAttributeFromGraphQLResult("vectors")
+)
+
+
+/**
+ * A component for displaying the `vectors` attribute of a template entity.
+ *
+ * This component checks if the `vectors` attribute exists on the `template` object. If `vectors` is undefined,
+ * the component returns `null` and renders nothing. Otherwise, it maps over the (optionally filtered) `vectors` array
+ * and displays a placeholder message and a JSON representation for each item.
+ *
+ * @component
+ * @param {Object} props - The props for the TemplateVectorsAttribute component.
+ * @param {Object} props.template - The object representing the template entity.
+ * @param {Array<Object>} [props.template.vectors] - An array of vector items associated with the template entity.
+ *   Each item is expected to have a unique `id` property.
+ * @param {Function} [props.filter=Boolean] - (Optional) A function to filter the vectors array before rendering.
+ *
+ * @returns {JSX.Element|null} A JSX element displaying the (filtered) `vectors` items or `null` if the attribute is undefined or empty.
+ *
+ * @example
+ * // Basic usage:
+ * const templateEntity = { 
+ *   vectors: [
+ *     { id: 1, name: "Vector Item 1" }, 
+ *     { id: 2, name: "Vector Item 2" }
+ *   ] 
+ * };
+ * <TemplateVectorsAttribute template={templateEntity} />
+ *
+ * @example
+ * // With a custom filter:
+ * <TemplateVectorsAttribute 
+ *   template={templateEntity}
+ *   filter={vector => vector.name.includes("1")}
+ * />
+ */
+export const TemplateVectorsAttribute_old = ({template, filter=Boolean, Visualiser=TrivialVisualiserDiv}) => {
+    const { vectors: unfiltered } = template
+    if (typeof unfiltered === 'undefined') return null
+    const vectors = unfiltered.filter(filter)
+    if (vectors.length === 0) return null
+    return (
+        <>
+            {vectors.map(
+                vector => <Visualiser id={vector.id} key={vector.id} vector={vector} />
+            )}
+        </>
+    )
+}
+
+/**
+ * Visualiser component for displaying a list of vector items using `TemplateVectorsAttribute`.
+ *
+ * Wraps the `TemplateVectorsAttribute` component, passing the given `items` as the `vectors` attribute
+ * on a synthetic `template` object. All other props are forwarded.
+ *
+ * @component
+ * @param {Object} props - Component props.
+ * @param {Array<Object>} props.items - The array of vector items to be visualized.
+ * @param {...any} [props] - Additional props forwarded to `TemplateVectorsAttribute` (e.g., `filter`).
+ *
+ * @returns {JSX.Element|null} Rendered list of vectors or `null` if none are provided.
+ *
+ * @example
+ * <VectorsVisualiser
+ *   items={[
+ *     { id: 1, name: "Vector 1" },
+ *     { id: 2, name: "Vector 2" }
+ *   ]}
+ *   filter={v => v.name.includes("1")}
+ * />
+ */
+const VectorsVisualiser = ({ items, ...props }) => 
+    <TemplateVectorsAttribute_old {...props} template={{ vectors: items }} />
+
+/**
+ * Infinite-scrolling component for the `vectors` attribute of a template entity.
+ *
+ * Uses the generic `InfiniteScroll` component to fetch, merge, and display the `vectors` array
+ * associated with the provided `template` object. It utilizes `VectorsVisualiser` for rendering,
+ * and handles pagination, lazy-loading, and merging of items as the user scrolls.
+ *
+ * @component
+ * @param {Object} props - Component props.
+ * @param {Object} props.template - The template entity containing the `vectors` array.
+ * @param {Array<Object>} [props.template.vectors] - (Optional) Preloaded vector items.
+ * @param {Object} [props.actionParams={}] - Optional extra parameters for the async fetch action (merged with pagination).
+ * @param {...any} [props] - Additional props passed to `InfiniteScroll` or `VectorsVisualiser`.
+ *
+ * @returns {JSX.Element} An infinite-scrolling list of vectors.
+ *
+ * @example
+ * <TemplateVectorsAttributeInfinite
+ *   template={{
+ *     vectors: [
+ *       { id: 1, name: "Vector 1" },
+ *       { id: 2, name: "Vector 2" }
+ *     ]
+ *   }}
+ * />
+ */
+export const TemplateVectorsAttributeInfinite = ({template, actionParams={}, ...props}) => { 
+    const {vectors} = template
+
+    return (
+        <InfiniteScroll 
+            {...props}
+            Visualiser={VectorsVisualiser} 
+            preloadedItems={vectors}
+            actionParams={{...actionParams, skip: 0, limit: 10}}
+            asyncAction={TemplateVectorsAttributeAsyncAction}
+        />
+    )
+}
+
+/**
+ * A lazy-loading component for displaying filtered `vectors` from a `template` entity.
+ *
+ * This component uses the `TemplateVectorsAttributeAsyncAction` to asynchronously fetch
+ * the `template.vectors` data. It shows a loading spinner while fetching, handles errors,
+ * and filters the resulting list using a custom `filter` function (defaults to `Boolean` to remove falsy values).
+ *
+ * Each vector item is rendered as a `<div>` with its `id` as both the `key` and the `id` attribute,
+ * and displays a formatted JSON preview using `<pre>`.
+ *
+ * @component
+ * @param {Object} props - The properties object.
+ * @param {Object} props.template - The template entity or identifying query variables used to fetch it.
+ * @param {Function} [props.filter=Boolean] - A filtering function applied to the `vectors` array before rendering.
+ *
+ * @returns {JSX.Element} A rendered list of filtered vectors or a loading/error placeholder.
+ *
+ * @example
+ * <TemplateVectorsAttributeLazy template={{ id: "abc123" }} />
+ *
+ * 
+ * @example
+ * <TemplateVectorsAttributeLazy
+ *   template={{ id: "abc123" }}
+ *   filter={(v) => v.status === "active"}
+ * />
+ */
+export const TemplateVectorsAttributeLazy = ({template, filter=Boolean, ...props}) => {
+    const {loading, error, entity, fetch} = useAsyncAction(TemplateVectorsAttributeAsyncAction, template, {deferred: true})
+    useEffect(() => {
+        fetch(template)
+    }, [template])
+
+    if (loading) return <LoadingSpinner />
+    if (error) return <ErrorHandler errors={error} />
+
+    return <TemplateVectorsAttribute_old template={entity} filter={filter} {...props}/>    
+}
+
+const TrivialVisualiserDiv = ({vector, children}) => <div>
+    Probably {'<VectorMediumCard vector={vector} />'} <br />
+    <pre>{JSON.stringify(vector, null, 4)}</pre>
+    {children}
+</div>
+
+/**
+ * Component to render the filtered `vectors` attribute of a template entity.
+ *
+ * Applies an optional filter function to the vectors array before rendering.
+ * Supports infinite scrolling to load more items lazily.
+ *
+ * The `Layout` prop is used as a wrapper component for each rendered item and
+ * is consistently applied in both static and infinite scroll rendering modes.
+ * If different layouts are desired for infinite vs static modes,
+ * consider conditionally passing different `Layout` props.
+ *
+ * @param {object} props - Component props.
+ * @param {object} props.template - The template entity containing the `vectors` array.
+ * @param {Array<object>} [props.template.vectors] - Array of vector items to render.
+ * @param {React.ComponentType} [props.Visualiser=TrivialVisualiserDiv] - Component to render each vector item.
+ *   Receives `vector` and optionally other props.
+ * @param {boolean} [props.infinite=true] - Whether to enable infinite scrolling.
+ * @param {React.ComponentType|string} [props.Layout=Col] - Wrapper component for each rendered item.
+ *   This component is used consistently for both static rendering and infinite scroll loading.
+ * @param {Function} [props.filter=Boolean] - Filter function to apply on vectors before rendering.
+ * @param {...any} props - Additional props forwarded to `Visualiser` and `InfiniteScroll`.
+ *
+ * @returns {JSX.Element|null} Rendered list or infinite scroll component, or null if no vectors.
+ *
+ * @example
+ * <TemplateVectorsAttribute
+ *   template={template}
+ *   Visualiser={VectorMediumCard}
+ *   Layout={Col}
+ *   filter={(v) => v.active}
+ *   infinite={true}
+ * />
+ */
+export const TemplateVectorsAttribute = ({
+    template,
+    Visualiser = TrivialVisualiserDiv,
+    infinite = true,
+    Layout = Col, // 'list' | 'grid' | 'infinite'
+    filter = Boolean,
+    ...props
+}) => {
+
+    const { vectors: unfiltered } = template
+    if (typeof unfiltered === 'undefined') return null
+    const vectors = unfiltered.filter(filter)
+    if (vectors.length === 0) return null
+
+
+
+    if (infinite) {
+        // Pro infinite scroll použijeme komponentu InfiniteScroll
+        // Visualiser zde je komponenta, která přijímá pole položek (items)
+        // a zobrazí je – proto vytvoříme wrapper, který předá Visualiser správně
+
+        const VisualiserWrapper = ({ items }) => ( 
+            <TemplateVectorsAttribute 
+                {...props}    
+                template={{vectors: items}} 
+                Visualiser={Visualiser} 
+                infinite={false} 
+                Layout={Layout} 
+                filter={filter}
+            />
+        );
+
+        return (
+            <InfiniteScroll
+                actionParams={{ ...template, skip: 0, limit: 10 }}
+                asyncAction={TemplateVectorsAttributeAsyncAction}
+                {...props}
+                Visualiser={VisualiserWrapper}
+                preloadedItems={vectors}
+            />
+        );
+    }
+
+    return (
+        <>
+        {vectors.map((vector) => (
+            <Layout key={vector.id}>
+                {vector && <Visualiser {...props} vector={vector} />}
+            </Layout>
+        ))}
+        </>
+    );
+};

package/src/_Template/Vectors/VectorAttribute.jsx

@@ -0,0 +1,56 @@
+import { CardCapsule } from "../Components/CardCapsule"
+import { Table } from "../Components/Table"
+import { Col } from "../../../../_template/src/Base/Components/Col"
+import { Row } from "../../../../_template/src/Base/Components/Row"
+
+export const VectorAttributeFactory = (attribute_name) => ({ item }) => {
+    const attribute_value = item?.[attribute_name] || []
+    return (
+        <Row key={attribute_name}>
+            <Col className="col-2"><b>{attribute_name}</b></Col>
+            <Col className="col-10">
+                <CardCapsule item={item}>
+                    <Table data={attribute_value} />
+                </CardCapsule>
+            </Col>
+        </Row>
+    )
+}
+
+export const VectorAttribute_ = ({ attribute_name, item }) => {
+    const attribute_value = item?.[attribute_name] || []
+    return (
+        <Row key={attribute_name}>
+            <Col className="col-2"><b>{attribute_name}</b></Col>
+            <Col className="col-10">
+                <CardCapsule item={item}>
+                    <Table data={attribute_value} />
+                </CardCapsule>
+            </Col>
+        </Row>
+    )
+}
+
+export const VectorAttribute = ({ attribute_name, item }) => {
+    const attribute_value = item?.[attribute_name] || []
+    return (
+        <CardCapsule item={item} title={attribute_name+'[]'}>
+            <Table data={attribute_value} />
+        </CardCapsule>
+    )
+}
+
+
+export const MediumCardVectors = ({ item }) => {
+    return (
+        <CardCapsule item={item}>
+            {Object.entries(item).map(([attribute_name, attribute_value]) => {
+                if (Array.isArray(attribute_value)) {
+                    return <VectorAttribute key={attribute_name} attribute_name={attribute_name} item={item} />
+                } else {
+                    return null
+                }
+            })}
+        </CardCapsule>
+    )
+}

package/src/_Template/Vectors/index.js

@@ -0,0 +1 @@
+export * from './TemplateVectorsAttribute'

package/src/_Template/WhatToDo.md

@@ -0,0 +1,44 @@
+
+
+## Base Copy
+
+- copy /_template/ directory to your place
+
+## Adapt to new type
+
+### Change URI locations
+- in Link.jsx file (see subdir ./components/) change LinkURI
+- in Link.jsx file change registerLink('YourGQLModel)
+
+### Register pages and components to Application
+- rename RouterSegments in Page/RouterSegments.jsx
+- insert RouterSegments into app router, so make them working
+
+
+At some point you should restart vite.
+
+- use http://localhost:8001/doc and graphiql at http://localhost:8001/gql to get queries and update AsyncActions, fragments, etc. in directory Queries
+  - readById
+  - readPage
+  - mutations (CUD)
+
+- try to navigate in your app to URI defined in Link to reach list of items `/template/YOUDEFINED/list/'
+- remove all errors until you get your app showing a table
+- try to navigate from table into individual items
+- check permission at API (source code etc.) to get info about neede roles for particular mutations 
+  - UserAbsoluteAccessControlExtension or RbacProviderExtension
+  - set
+
+- Change LargeCard, add there more buttons
+
+- Update MediumContent.jsx file to show more or less data related to you entity
+- Update MediumEditableContent.jsx file to allow edit of more or less data
+
+
+## Add new Mutations
+
+- check gqlendpoint to cover all available mutations with appropriate permissions
+  
+### Update filters
+
+- Set Filter component, correct it at PageVector, do not forget to use appropriate name for query param in url

package/src/_Template/index.js

@@ -0,0 +1,71 @@
+
+export * from './Components'
+export * from './Scalars'
+export * from './Vectors'
+export * from './Queries'
+export * from './Pages'
+
+import { 
+    CardCapsule,
+    Children,
+    CUDButton,
+    LargeCard,
+    Link,
+    MediumContent,
+    MediumCard,
+
+    MediumEditableContent,
+    LiveEdit
+
+} from './Components'
+
+import { 
+    EditPage,
+    Page,
+    PageNavbar,
+    TemplateRouterSegments,
+    VectorPage
+} from './Pages'
+
+// import { UIActions } from './Queries'
+
+export const TemplateUI = {
+    CardCapsule,
+    Children,
+    CUDButton,
+    LargeCard,
+    Link,
+    MediumContent,
+    MediumCard,
+
+    MediumEditableContent,
+    LiveEdit,
+
+    Page,
+    VectorPage,
+    EditPage,
+    PageNavbar,
+    TemplateRouterSegments
+}
+
+
+
+// export const TemplateUI = {
+//     CardCapsule: withUI(_TemplateUI)(_TemplateUI.CardCapsule),
+//     Children: withUI(_TemplateUI)(_TemplateUI.Children),
+//     CUDButton: withUI(_TemplateUI)(_TemplateUI.CUDButton),
+//     LargeCard: withUI(_TemplateUI)(_TemplateUI.LargeCard),
+//     Link: withUI(_TemplateUI)(_TemplateUI.Link),
+//     MediumContent: withUI(_TemplateUI)(_TemplateUI.MediumContent),
+//     MediumCard: withUI(_TemplateUI)(_TemplateUI.MediumCard),
+
+//     MediumEditableContent: withUI(_TemplateUI)(_TemplateUI.MediumEditableContent),
+//     LiveEdit: withUI(_TemplateUI)(_TemplateUI.LiveEdit),
+
+//     Page: withUI(_TemplateUI)(_TemplateUI.Page),
+//     VectorPage: withUI(_TemplateUI)(_TemplateUI.VectorPage),
+//     EditPage: withUI(_TemplateUI)(_TemplateUI.EditPage),
+//     PageNavbar: withUI(_TemplateUI)(_TemplateUI.PageNavbar),
+//     RouterSegment: withUI(_TemplateUI)(_TemplateUI.RouterSegment)
+// }
+

package/src/index.js

@@ -0,0 +1,8 @@
+// export * as GroupGQLModel from "./GroupGQLModel"
+// export * as UserGQLModel from "./UserGQLModel"
+// export * as RoleGQLModel from "./RoleGQLModel"
+// export * as MembershipGQLModel from "./MembershipGQLModel"
+
+// export * as GroupTypeGQLModel from "./GroupTypeGQLModel"
+// export * as RoleTypeGQLModel from "./RoleTypeGQLModel"
+export * from "./Base"

package/src/uriroot.js

@@ -0,0 +1,158 @@
+/**
+ * Očistí segment URL/URI od přebytečných lomítek na začátku a na konci.
+ *
+ * Používá se pro segmenty `app`, `model`, `action` tak, aby výsledná cesta
+ * nevznikala jako `//app//model/...` a aby se dalo bezpečně skládat i z hodnot,
+ * které už obsahují `/`.
+ *
+ * @private
+ * @param {any} s
+ *   Hodnota segmentu (typicky string); `null/undefined` se převede na prázdný string.
+ * @returns {string}
+ *   Segment bez úvodních a koncových `/`.
+ */
+const clean = (s) => String(s ?? "").replace(/^\/+|\/+$/g, "");
+
+/**
+ * Vytvoří "stringovatelný" objekt reprezentující kanonickou aplikací definovanou URI cestu
+ * ve tvaru:
+ *
+ * - bez `:id`: `/{app}/{model}/{action}`
+ * - s `:id`:   `/{app}/{model}/{action}/{:id}`
+ *
+ * Objekt je určený pro postupné skládání a odvozování cest napříč aplikací:
+ * - sdílení společného základu (např. `app` nebo `app+model`)
+ * - tvorbu odvozenin přes `.change(...)` bez mutace původního objektu
+ * - pohodlné použití v routeru, linkách a šablonách díky "stringovatelnosti"
+ *
+ * ### Stringovatelnost
+ * Vrácený objekt se chová jako string:
+ * - `String(obj)` vrátí finální cestu
+ * - template literal: `` `${obj}` `` vrátí finální cestu
+ * - `obj.path` obsahuje totéž explicitně
+ *
+ * ### Odvozování bez mutace (immutable styl)
+ * Metoda `.change(patch)` vrací NOVÝ URI objekt s aplikovanými změnami.
+ * Původní objekt zůstává nedotčen, takže je bezpečné ho sdílet napříč moduly.
+ *
+ * ### Zkratky
+ * Kromě `.change(...)` poskytuje i zkratky:
+ * - `.app("...")`
+ * - `.model("...")`
+ * - `.action("...")`
+ * - `.id(true|false)` (alias pro `withId`)
+ * - `.idParam(":id")` (změna názvu parametru id)
+ *
+ * @example
+ * // Základ pro konkrétní model:
+ * const GroupView = uri({ app: "app", model: "group", action: "view" });
+ *
+ * String(GroupView)        // "/app/group/view"
+ * String(GroupView.id())   // "/app/group/view/:id"
+ *
+ * @example
+ * // Odvozené akce nad stejným modelem:
+ * const Group = uri({ app: "app", model: "group", action: "view" });
+ * const GroupEdit = Group.action("edit").id(true);
+ * const GroupDelete = Group.action("delete").id(true);
+ *
+ * String(GroupEdit)   // "/app/group/edit/:id"
+ * String(GroupDelete) // "/app/group/delete/:id"
+ *
+ * @example
+ * // Přepnutí id parametru:
+ * const UserView = uri({ app: "app", model: "user", action: "view" }).id(true).idParam(":userId");
+ * String(UserView) // "/app/user/view/:userId"
+ *
+ * @function uri
+ * @param {object} [options]
+ * @param {string} [options.app]
+ *   První segment cesty (např. "app"). Přebytečné "/" na začátku/konci se odstraní.
+ * @param {string} [options.model]
+ *   Druhý segment cesty (např. "group", "roleType"...).
+ * @param {string} [options.action]
+ *   Třetí segment cesty (např. "view", "create", "edit", "delete", "rolesOn"...).
+ * @param {boolean} [options.withId=false]
+ *   Pokud `true`, připojí se na konec ještě segment s parametrem id (`/:idParam`).
+ * @param {string} [options.idParam=":id"]
+ *   Název parametru pro identifikátor entity. Můžeš zadat `":id"` nebo `"id"` – v obou
+ *   případech bude interně normalizováno na formát s dvojtečkou (např. `":id"`).
+ *
+ * @returns {UriBuilder}
+ *   "Stringovatelný" objekt s výslednou cestou, segmenty a metodami pro odvozování.
+ *
+ * @typedef {object} UriBuilder
+ * @property {string} path
+ *   Finální cesta (např. `"/app/group/view"` nebo `"/app/group/view/:id"`).
+ * @property {{app:string, model:string, action:string, withId:boolean, idParam:string}} segments
+ *   Normalizované segmenty, ze kterých byla cesta složena.
+ *   Pozn.: pokud `segments` budeš ručně měnit, `path` se tím nezmění (je spočítaný).
+ *   Doporučení: segmenty používej jen pro čtení.
+ *
+ * @property {() => string} toString
+ *   Vrací `path`. Umožňuje použití v template literal a při `String(obj)`.
+ * @property {() => string} valueOf
+ *   Vrací `path`. Doplňková string/primitive konverze.
+ * @property {(hint: "number"|"string"|"default") => string} [Symbol.toPrimitive]
+ *   Vrací `path` pro implicitní konverzi (např. `` `${obj}` ``).
+ *
+ * @property {(patch?: Partial<UriPatch>) => UriBuilder} change
+ *   Vytvoří nový `UriBuilder` s aplikovaným patchem (libovolná část URI může být změněna).
+ *
+ * @property {(app: string) => UriBuilder} app
+ *   Zkratka pro `change({ app })`.
+ * @property {(model: string) => UriBuilder} model
+ *   Zkratka pro `change({ model })`.
+ * @property {(action: string) => UriBuilder} action
+ *   Zkratka pro `change({ action })`.
+ * @property {(on?: boolean) => UriBuilder} id
+ *   Zkratka pro `change({ withId: on })`. Default `true`.
+ * @property {(p?: string) => UriBuilder} idParam
+ *   Zkratka pro `change({ idParam: p })`. Default `":id"`.
+ *
+ * @typedef {object} UriPatch
+ * @property {string} [app]
+ * @property {string} [model]
+ * @property {string} [action]
+ * @property {boolean} [withId]
+ * @property {string} [idParam]
+ */
+export const uri = ({ app="_", model="_", action="view", withId = false, idParam = ":id" } = {}) => {
+    const seg = {
+        app: clean(app),
+        model: clean(model),
+        action: clean(action),
+        withId: Boolean(withId),
+        idParam: String(idParam).startsWith(":") ? String(idParam) : `:${String(idParam)}`,
+    };
+
+    const base = `/${seg.app}/${seg.model}/${seg.action}`.replace(/\/+/g, "/");
+    const path = seg.withId ? `${base}/${seg.idParam}` : base;
+
+    const obj = {
+        path,
+        segments: seg,
+
+        // stringovatelnost
+        toString() { return path; },
+        valueOf() { return path; },
+        [Symbol.toPrimitive]() { return path; },
+
+        // "immutable" změna: vrátí nový objekt
+        change(patch = {}) {
+            return uri({ ...seg, ...patch });
+        },
+
+        // volitelné zkratky
+        app(app) { return obj.change({ app }); },
+        model(model) { return obj.change({ model }); },
+        action(action) { return obj.change({ action }); },
+        id(on = true) { return obj.change({ withId: on }); },
+        idParam(p = ":id") { return obj.change({ idParam: p }); },
+    };
+
+    return obj;
+};
+
+export const URIRoot = "/template"
+export const URIRootObj = uri({ app: URIRoot })