@e280/quay 0.0.0-1

package/s/genius/parts/hy-tree.ts

@@ -0,0 +1,142 @@
+
+import {Kv, collect} from "@e280/kv"
+
+export type HyId = string
+export type HyItem = {parent: HyId | null, children: HyId[]}
+type HyRecord = [parent: HyId | null, children: HyId[]]
+
+/**
+ * Async hierarchy of nestable items.
+ *  - items can have multiple children.
+ *  - items can only have one parent.
+ *  - items can be orphans (bring your own concept of a "root").
+ */
+export class HyTree {
+	constructor(private records: Kv<HyRecord>) {}
+
+	async has(id: HyId) {
+		return this.records.has(id)
+	}
+
+	async get(id: HyId): Promise<HyItem | undefined> {
+		const record = await this.records.get(id)
+		if (record) {
+			const [parent, children] = record
+			return {parent, children}
+		}
+	}
+
+	async gets(...ids: HyId[]): Promise<(HyItem | undefined)[]> {
+		const records = await this.records.gets(...ids)
+		return records.map(r => {
+			if (!r) return undefined
+			const [parent, children] = r
+			return {parent, children}
+		})
+	}
+
+	async require(id: HyId): Promise<HyItem> {
+		const record = await this.records.require(id)
+		const [parent, children] = record
+		return {parent, children}
+	}
+
+	async requires(...ids: HyId[]): Promise<HyItem[]> {
+		const records = await this.records.requires(...ids)
+		return records.map(([parent, children]) => ({parent, children}))
+	}
+
+	/** establish an id as a root with no parents, but ready to accept children */
+	async establishRoot(root: HyId) {
+		return this.records.set(root, [null, []])
+	}
+
+	/** give a parent some children  */
+	async attach(parent: HyId, ...children: HyId[]) {
+		children = [...new Set(children)]
+		const parentItem = await this.require(parent)
+		const siblings = new Set(parentItem.children)
+		const childItems = await this.gets(...children)
+		const newcomers: [HyId, HyRecord][] = []
+
+		for (const [index, id] of children.entries()) {
+			const item = childItems.at(index)
+
+			// child already in tree
+			if (item && item.parent) throw new Error(`child already has parent`)
+
+			// child not in tree yet, remember to save it
+			else newcomers.push([id, [parent, []]])
+
+			// add to siblings set
+			siblings.add(id)
+		}
+
+		// save all new children
+		await this.records.sets(...newcomers)
+
+		// save updated parent item
+		await this.records.set(parent, [parentItem.parent, [...siblings]])
+	}
+
+	/** detach this id from its parent in the hierarchy */
+	async detach(id: HyId) {
+		const item = await this.get(id)
+		if (!item) return undefined
+
+		if (item.parent) {
+			const parentItem = await this.require(item.parent)
+			const siblings = new Set(parentItem.children)
+			siblings.delete(id)
+
+			// save the parent item with removed child
+			await this.records.set(item.parent, [parentItem.parent, [...siblings]])
+
+			// save the child with null parent
+			await this.records.set(id, [null, item.children])
+		}
+	}
+
+	/** destroy all relations associated with this id, and all its descendants */
+	async destroy(id: HyId) {
+		await this.detach(id)
+		const tree = await collect(this.crawl(id))
+		const ids = tree.map(({id}) => id)
+		await this.records.del(...ids)
+	}
+
+	/** delete absolutely everything */
+	async clear() {
+		await this.records.clear()
+	}
+
+	/** iterate over all root items */
+	async *roots() {
+		for await (const [id, [parent, children]] of this.records.entries())
+			if (parent === null)
+				yield {id, item: {parent, children}} as {id: HyId, item: HyItem}
+	}
+
+	/** iterate over this id and all its descendants */
+	async *crawl(
+			id: HyId,
+			predicate: (id: HyId, path: HyId[]) => Promise<boolean> = async() => true,
+		) {
+
+		const todo: [item: HyId, path: HyId[]][] = [[id, []]]
+		const seen = new Set<HyId>()
+
+		while (todo.length) {
+			const [id, path] = todo.shift()!
+			if (seen.has(id) || !await predicate(id, path)) continue
+			seen.add(id)
+
+			const item = await this.require(id)
+			yield {id, item, path} as {id: HyId, item: HyItem, path: HyId[]}
+
+			for (const childId of item.children)
+				todo.push([childId, [...path, id]])
+		}
+	}
+}
+

package/s/genius/quay.md

@@ -0,0 +1,13 @@
+
+# 🪝 Quay integration
+
+```ts
+import {Quay, Opfs, OpfsSchema} from "@e280/quay"
+
+const quay = new Quay()
+const opfs = await Opfs.setup()
+const group = quay.group<OpfsSchema>(opfs)
+
+register(group.elements())
+```
+

package/s/genius/turbo.md

@@ -0,0 +1,21 @@
+
+# ⚡ Turbo
+
+**Turbo** is a turbocharger for reading and writing files in [OPFS](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system).
+
+It provides high-performance multithreaded low-level read/write access by automatically scheduling parallel tasks across a pool of web workers.
+
+- 📂 **OPFS** — files stay local on the user's device
+- 🧵 **Multithreaded** — goes fast with no ui jank
+- ⚙️ **Low-level** — streaming byte-level access
+- 🔒 **Smart** — prevents funky race conditions
+
+<br/>
+
+---
+
+> ### Wip: implementation plan
+> - use comrade for worker pooling
+> - workers use opfs createSyncAccessHandle, make TransformStream readable/writable pair, wire it to the file stream, transfer the other end to the main thread, voila, connected
+> - we have to do some big-brain horseshit to schedule tasks in a way to maximize parallelism while respecting ongoing locks
+

package/s/genius/twig.ts

@@ -0,0 +1,34 @@
+
+/**
+ * 🌿 Async source for loading items into Quay.
+ * - crawlable and callable by the ui
+ * - the functions provided are available for the ui user
+ * - as we crawl, every item we see is cached for sync rendering
+ * - minimal so as to be compatible even with raw opfs
+ * - Opfs, Cellar, etc, will literally provide Twig implementations
+ */
+export type Twig<T extends Twig = any> = {
+	readonly id: string
+	name: string
+	parent: T | null
+
+	rename?: (name: string) => Promise<void>
+	delete?: () => Promise<void>
+	move?: (o: {parent: T}) => Promise<void>
+	copy?: (o: {parent: T, name: string}) => Promise<void>
+
+	container?: {
+		create(o: CreationOptions): Promise<T>
+		children(o?: ListingOptions): Promise<T[]>
+		crawl(predicate: (item: T, ancestors: T[]) => Promise<boolean>): AsyncIterable<T>
+	}
+}
+
+export type Lens<T extends Twig = any> = (item: T) => boolean
+export type WritingOptions = {}
+export type ReadingOptions = {}
+export type CreationOptions = {}
+export type ListingOptions<T extends Twig = any> = {
+	lens?: Lens<T>
+}
+

package/s/index.html.ts

@@ -0,0 +1,89 @@
+import "@benev/slate/x/node.js"
+import {template, html, easypage, headScripts, git_commit_hash, read_file, renderSocialCard, read_json} from "@benev/turtle"
+
+const domain = "quay.e280.org"
+const favicon = "/assets/favicon.png"
+
+export default template(async basic => {
+	const path = basic.path(import.meta.url)
+	const hash = await git_commit_hash()
+	const version = (await read_json("package.json")).version as string
+
+	return easypage({
+		path,
+		dark: true,
+		title: "Quay",
+		css: "demo/main.css",
+		head: html`
+			<link rel="icon" href="${favicon}"/>
+			<meta data-commit-hash="${hash}"/>
+
+			${renderSocialCard({
+				themeColor: "#eb6f1d",
+				siteName: domain,
+				title: "Quay — File-browser UI Framework",
+				description: "Customizable outliner web ui toolkit for nested things",
+				image: `https://${domain}${favicon}`,
+				url: `https://${domain}/`,
+			})}
+
+			${headScripts({
+				devModulePath: await path.version.root("demo/main.bundle.js"),
+				prodModulePath: await path.version.root("demo/main.bundle.min.js"),
+				importmapContent: await read_file("x/importmap.json"),
+			})}
+
+			<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css" />
+			<!-- loading every sholeace component for now (should be cherry picked instead) --!>
+			<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/shoelace.js" ></script>
+		`,
+		body: html`
+			<header class=title>
+				<img alt="" src="/assets/favicon.png"/>
+				<div>
+					<h1>Quay</h1>
+					<span class=version>v${version}</span>
+				</div>
+			</header>
+
+			<div class=components>
+
+				<div class="component dropzone">
+					<h4>quay-dropzone</h2>
+					<quay-dropzone></quay-dropzone>
+				</div>
+
+				<div class="component outliner">
+					<h4>quay-outliner</h2>
+					<quay-outliner></quay-outliner>
+				</div>
+
+				<div class="component searchbar">
+					<h4>quay-searchbar</h2>
+					<quay-searchbar></quay-searchbar>
+				</div>
+
+				<div class="component breadcrumb">
+					<h4>quay-breadcrumb</h2>
+					<quay-breadcrumb></quay-breadcrumb>
+				</div>
+
+				<div class="component filter">
+					<h4>quay-filter</h2>
+					<quay-filter></quay-filter>
+				</div>
+
+				<div class="component sort">
+					<h4>quay-sort</h2>
+					<quay-sort></quay-sort>
+				</div>
+
+				<div class="component browser">
+					<h4>quay-browser</h2>
+					<quay-browser></quay-browser>
+				</div>
+
+			</div>
+		`,
+	})
+})

package/s/index.ts

@@ -0,0 +1,14 @@
+
+export {register, css} from "@benev/slate"
+
+export * from "./cellar/index.js"
+
+export * from "./dom/components.js"
+import {Permissions} from "./logic/permissions.js"
+
+const Quay = {
+	permissions: Permissions,
+}
+
+export default Quay
+

package/s/logic/aspects/codex/codex.ts

@@ -0,0 +1,46 @@
+
+import {MapG} from "@e280/stz"
+
+import {Clade} from "./parts/clade.js"
+import {Taxonomy} from "./parts/taxonomy.js"
+import {Hierarchy} from "./parts/hierarchy.js"
+import {CodexItem} from "./parts/codex-item.js"
+import {generateId} from "./utils/generate-id.js"
+import {Id, Schema, Taxons} from "./parts/types.js"
+
+export class Codex<Sc extends Schema> {
+	static setup<Sc extends Schema>(taxons: Taxons<Sc>) {
+		const taxonomy = new Taxonomy<Sc>(taxons)
+		const clade = new Clade(taxonomy)
+		const hierarchy = new Hierarchy()
+		return new this(clade, hierarchy)
+	}
+
+	#items = new MapG<Id, CodexItem<Sc>>()
+
+	constructor(
+		public clade: Clade<Sc>,
+		public hierarchy: Hierarchy,
+	) {}
+
+	/** create an item, not yet added to hierarchy */
+	create<K extends keyof Sc["specimens"]>(kind: K, specimen: Sc["specimens"][K]) {
+		const id = generateId()
+		this.clade.setSpecimen(id, kind, specimen)
+		const item = new CodexItem(this, id)
+		this.#items.set(id, item)
+		return item.signal.value
+	}
+
+	/** add an item to the hierachy as a root root */
+	root<I extends CodexItem<Sc>>(item: I) {
+		this.hierarchy.establishRoot(item.id)
+		return item.signal.value
+	}
+
+	/** get an item by its id */
+	require(id: Id): CodexItem<Sc> {
+		return this.#items.require(id).signal.value
+	}
+}
+

package/s/logic/aspects/codex/example.ts

@@ -0,0 +1,65 @@
+
+import "@benev/slate/x/node.js"
+import {repeat_string} from "@benev/turtle"
+
+import {Codex} from "./codex.js"
+import {AsSchema, Taxon} from "./parts/types.js"
+
+//
+// a Schema is all the type information for customizing Quay
+//  - *taxon* is like "folders have this icon"
+//  - *specimen* is like "this particular folder has this label"
+//
+export type FilesystemSchema = AsSchema<{
+	taxon: Taxon
+	specimens: {
+		folder: {label: string}
+		file: {label: string}
+	}
+}>
+
+// we create a codex that uses our schema, and specifies these icons
+const codex = Codex.setup<FilesystemSchema>({
+	folder: {icon: "📁"},
+	file: {icon: "📄"},
+})
+
+// let's create a folder with some crap
+const folder = codex.create("folder", {label: "project"})
+const readme = codex.create("file", {label: "README.md"})
+const changelog = codex.create("file", {label: "CHANGELOG.md"})
+
+// let's create a subfolder with more crap
+const src = codex.create("folder", {label: "src"})
+const index = codex.create("file", {label: "index.ts"})
+const types = codex.create("file", {label: "types.ts"})
+
+// we attach the folder as the root, and attach its children
+codex.root(folder)
+	.attach(readme)
+	.attach(changelog)
+	.attach(src) // <-- this is the subfolder
+
+// and we attach the subfolder items to it
+src
+	.attach(index)
+	.attach(types)
+
+	//                   we can crawl any folder!
+	//                                    👇
+for (const [item, ancestors] of folder.crawl()) {
+	const indent = repeat_string(ancestors.length, "  ")
+	const specimen = item.specimen
+	const label = item.kind === "folder"
+		? specimen.label + "/"
+		: specimen.label
+	console.log(indent + label)
+}
+
+// project/
+//   README.md
+//   CHANGELOG.md
+//   src/
+//     index.ts
+//     types.ts
+

package/s/logic/aspects/codex/parts/clade.ts

@@ -0,0 +1,28 @@
+
+import {MapG, sub} from "@e280/stz"
+import {Taxonomy} from "./taxonomy.js"
+import {AnySpecimen, Id, Kind, Schema} from "./types.js"
+
+/** Tracks what kind and specimen data is associated with each item id. */
+export class Clade<Sc extends Schema> {
+	onChange = sub()
+	#specimens = new MapG<Id, [Kind<Sc>, AnySpecimen<Sc>]>()
+
+	constructor(public taxonomy: Taxonomy<Sc>) {}
+
+	getSpecimen<K extends Kind<Sc> = Kind<Sc>>(id: string) {
+		return this.#specimens.require(id) as [K, Sc["specimens"][K]]
+	}
+
+	setSpecimen<K extends Kind<Sc>>(id: string, kind: K, specimen: Sc["specimens"][K]) {
+		this.#specimens.set(id, [kind, specimen])
+		this.onChange.pub()
+	}
+
+	query<K extends Kind<Sc> = Kind<Sc>>(id: Id) {
+		const [kind, specimen] = this.getSpecimen<K>(id)
+		const taxon = this.taxonomy.taxon(kind)
+		return {kind, taxon, specimen}
+	}
+}
+

package/s/logic/aspects/codex/parts/codex-item.ts

@@ -0,0 +1,94 @@
+
+import {signal} from "@benev/slate"
+import {Codex} from "../codex.js"
+import {Id, Kind, Schema} from "./types.js"
+
+/**
+ * Codex Item
+ * 	- Quay's concept of a nestable thing.
+ * 	- ergonomic handle which consolidates taxonomy, clade, and hierarchy functionality.
+ */
+export class CodexItem<Sc extends Schema = any, K extends Kind<Sc> = Kind<Sc>> {
+	signal = signal(this)
+
+	constructor(
+		private codex: Codex<Sc>,
+		public id: Id,
+	) {}
+
+	get kind(): K {
+		return this.codex.clade.query<K>(this.id).kind
+	}
+
+	isKind<K2 extends Kind<Sc>>(kind: K2): this is CodexItem<Sc, K2> {
+		return (kind as any === this.kind)
+	}
+
+	/** get information about the type of entity */
+	get taxon(): Sc["taxon"] {
+		return this.codex.clade.query(this.id).taxon
+	}
+
+	/** get information about this specific entity */
+	get specimen(): Sc["specimens"][K] {
+		return this.codex.clade.query<K>(this.id).specimen
+	}
+
+	/** get this item's parent item, or undefined if it's not attached */
+	get parent(): CodexItem<Sc> | undefined {
+		const parent = this.codex.hierarchy.getParent(this.id)
+		return parent
+			? this.codex.require(parent) as CodexItem<Sc>
+			: undefined
+	}
+
+	/** get an array of this item's children */
+	get children(): CodexItem<Sc>[] {
+		// TODO actually replace this with a children() iterator, could be a perf win for supermassive sets
+		return [...this.codex.hierarchy.getChildren(this.id)]
+			.map(id => this.codex.require(id))
+	}
+
+	/** add items as children */
+	attach(...items: CodexItem<Sc>[]) {
+		this.codex.hierarchy.attach(this.id, ...items.map(i => i.id))
+		this.signal.publish()
+		return this
+	}
+
+	/** detach this item from the hierarchy completely */
+	detach() {
+		this.codex.hierarchy.detach(this.id)
+		this.signal.publish()
+	}
+
+	/** create a new item that will be a child */
+	create<K extends keyof Sc["specimens"]>(kind: K, specimen: Sc["specimens"][K]) {
+		const item = this.codex.create(kind, specimen)
+		this.attach(item)
+		return item
+	}
+
+	/** create a new item that will be a child */
+	destroy() {
+		this.codex.hierarchy.destroy(this.id)
+		this.signal.publish()
+	}
+
+	/** iterate over this item and all its descendants */
+	*crawl(predicate: (item: CodexItem<Sc>, path: CodexItem<Sc>[]) => boolean = () => true) {
+		const iterator = this.codex.hierarchy.crawl(
+			this.id,
+			(id, path) => predicate(
+				this.codex.require(id),
+				path.map(id => this.codex.require(id)),
+			)
+		)
+		for (const [id, path] of iterator)
+			yield [
+				this.codex.require(id),
+				path.map(id => this.codex.require(id)),
+			] as [CodexItem<Sc>, CodexItem<Sc>[]]
+	}
+}
+

package/s/logic/aspects/codex/parts/hierarchy.ts

@@ -0,0 +1,82 @@
+
+import {MapG} from "@e280/stz"
+import {Id} from "./types.js"
+
+/**
+ * Tree of nestable things.
+ *  - Things can have multiple children.
+ *  - Things can only have one parent.
+ *  - Things can be orphans (bring your own concept of a "root").
+ */
+export class Hierarchy {
+	#children = new MapG<Id, Set<Id>>()
+	#parents = new MapG<Id, Id>()
+
+	has(id: Id) {
+		return this.#children.has(id)
+	}
+
+	getChildren(id: Id) {
+		return this.#children.require(id)
+	}
+
+	getParent(id: Id) {
+		return this.#parents.get(id)
+	}
+
+	/** establish an id as a root with no parents, but ready to accept children */
+	establishRoot(root: Id) {
+		this.#children.set(root, new Set())
+	}
+
+	/** give a parent some children  */
+	attach(parent: Id, ...children: Id[]) {
+		const siblings = this.getChildren(parent)
+		for (const childId of children) {
+			if (this.getParent(childId))
+				throw new Error(`child already has parent`)
+			siblings.add(childId)
+			this.#parents.set(childId, parent)
+			this.#children.set(childId, new Set())
+		}
+	}
+
+	/** detach this id from its parent in the hierarchy */
+	detach(id: Id) {
+		if (!this.has(id))
+			return undefined
+		const parent = this.getParent(id)
+		if (parent) {
+			const siblings = this.getChildren(parent)
+			siblings.delete(id)
+			this.#parents.delete(id)
+		}
+	}
+
+	/** destroy all relations associated with this id, and all its descendants */
+	destroy(id: Id) {
+		const tree = [...this.crawl(id)]
+		for (const [id] of tree) {
+			this.#children.delete(id)
+			this.#parents.delete(id)
+		}
+	}
+
+	/** iterate over this id and all its descendants */
+	*crawl(id: Id, predicate: (id: Id, path: Id[]) => boolean = () => true) {
+		const todo: [Id, Id[]][] = [[id, []]]
+		const seen = new Set<Id>()
+
+		while (todo.length) {
+			const [id, path] = todo.shift()!
+			if (seen.has(id) || !predicate(id, path)) continue
+			seen.add(id)
+
+			yield [id, path] as [Id, Id[]]
+
+			for (const childId of this.getChildren(id))
+				todo.push([childId, [...path, id]])
+		}
+	}
+}
+

package/s/logic/aspects/codex/parts/taxonomy.ts

@@ -0,0 +1,18 @@
+
+import {MapG} from "@e280/stz"
+import {Kind, Schema, Taxons} from "./types.js"
+
+/** Defines the static details about each "kind" of data */
+export class Taxonomy<Sc extends Schema> {
+	#taxons = new MapG<Kind<Sc>, Sc["taxon"]>()
+
+	constructor(taxons: Taxons<Sc>) {
+		for (const [kind, taxon] of Object.entries(taxons))
+			this.#taxons.set(kind, taxon)
+	}
+
+	taxon<K extends Kind<Sc>>(kind: K) {
+		return this.#taxons.require(kind) as Sc["taxon"]
+	}
+}
+

package/s/logic/aspects/codex/parts/types.ts

@@ -0,0 +1,23 @@
+
+import {Content} from "@benev/slate"
+
+export type Id = string
+
+export type Taxon = {
+	icon: Content
+}
+
+export type Specimen = {label: string}
+
+export type Specimens = {[key: string]: Specimen}
+export type AsSpecimens<S extends Specimens> = S
+
+export type Schema = {
+	taxon: Taxon
+	specimens: Specimens
+}
+export type AsSchema<Sc extends Schema> = Sc
+export type Kind<Sc extends Schema> = keyof Sc["specimens"]
+export type Taxons<Sc extends Schema> = {[K in Kind<Sc>]: Sc["taxon"]}
+export type AnySpecimen<Sc extends Schema> = Sc["specimens"][Kind<Sc>]
+

package/s/logic/aspects/codex/utils/generate-id.ts

@@ -0,0 +1,7 @@
+
+import {Hex} from "@e280/stz"
+
+export function generateId() {
+	return Hex.random()
+}
+