@witchcraft/layout 0.1.3 → 0.2.0

package/README.md

@@ -112,38 +112,25 @@ This is done like this to make it easy to keep the dimensions rounded to x decim
 
 ## Configuration
 
-There are a few variables that need to be used nearly everywhere such as `SCALE` and `SNAP_PERCENT_{X/Y}`. 
+There are a few variables that need to be used nearly everywhere internally such as `settings.scale`. 
 
-While all function that need them, can also be called with params to override them, it's much easier to just manage them globally. 
-
-They are exported from `/settings.js` and stored in a variable called `globalOptions` which you can modify, but helpers are provided for getting/setting the information we actually want to extract using these variables, `maxInt`, `margin`, `snapPoint`.
+To avoid having to pass them around into functions,  they are exported from `/settings.js` and stored in a class instance called `settings` with special getters on the non-scaled values to automatically set scaled ones.
 
 ```ts
-import {
-	globalOptions,
-	getMaxInt,
-	// this is called snapPoint because it's type looks like a point
-	// but it's more like it describes snap steps / distance in x/y
-	getSnapPoint,
-	setScale,
-	setSnapAmount
-} from "@witchcraft-layout/settings.js"
+import { settings } from "@witchcraft-layout/settings.js"
 
 // the function checks the max number is safe to use (using `isSafeInteger`)
 // 3 decimal points of precision
-setScale(3) 
+settings.scale = 3 // setter forces recacl of other values
+settings.maxInt; // 100000 (100 * (10 ** 3))
 // snap to 1%
-setSnapPercentage(1) 
+settings.snapPoint = 1
 // snap x/y differently
-setSnapPercentage({ x: 1, y: 2 })
-setMarginPercentage(1)
+settings.snapPoint = { x: 1, y: 2 }
+settings.minSize = 5 (5%)
 
-// like doing const maxInt = globalOptions.maxInt
-const maxInt = getMaxInt() // 100000
-const snapAmountPoint = getSnapPoint() // { x: 1000, y: 1000 }
-const marginSize = getMarginSize() // { width: 1000, height: 1000 }
 ```
-**NOTE: If you are saving layouts, if you change the snap or the margins to a bigger value, old layouts will become "invalid".** The should still load and you should be able to close frames, but it's not guaranteed they'll function correctly.
+**NOTE: If you are saving layouts, if you change the snap or the min size to a bigger value, old layouts will become "invalid".** They should still load and you should be able to close frames, but it's not guaranteed they'll function correctly with other actions.
 
 There are utilities for converting between non-scaled and scaled values if you need to:
 
@@ -190,6 +177,16 @@ Edges and Decos are very simple and there are various utilies like `getVisualEdg
 
 This has the benefit for edges, that the grabable area can be easily adjusted and bigger than the displayed edge.
 
+## Making Changes
+
+The majority of actions are done in two steps:
+
+1. `get*Info` (e.g. `getFrameSplitInfo`) functions that return a `LayoutChange` object. These don't mutate the window and return the changes needed to apply the function. They can also be used to just check if the action can be done.
+2. `applyFrameChanges` which applies these changes by mutating the window.
+
+`get*Info` functions can return KnownErrors (e.g. out of bounds, can't split, no space, etc. see the `LAYOUT_ERROR` enum), which depending on the situation can be used to show an error decoration or just plain ignored.
+They only throw for logical errors (e.g. passing an invalid frame id, trying to undock an undocked frame) which indicate errors in your calling code.
+
 ## Dragging
 
 Then you will need to add dragging. This is not implemented by default (except for vue) as the state and rendering of a layout being dragged like this is almost always tightly coupled with whatever framework you're using and how you've structured your app. What I've figured out how to separate such as the `DragDirectionStore` and the drag action handlers is in `/drag`.
@@ -203,16 +200,15 @@ Add a `pointerdown` handler to all the edges.
 You can then use `toWindowCoord` to translate the event coordinates into a point.
 
 Before using it, you should be sure the window's coordinates are updated as this requires knowing the x/y px offset and the window dimensions.
-
 ```ts
 const point = toWindowCoord(win, e, snapPoint) // snapPoint is optional, it uses the global settings
-```
 
 One drag starts, I suggest making a copy of the original positions in case you need to cancel the drag. This can be further optimized by only cloning and modifying the touching frames and overlaying them over the unmoved edges to render them. See [Overlayed Frames Technique](#overlayed-frames-technique) below.
 
 You can use the `DragDirectionStore `to help keep track of which direction the user is dragging.
 
 Minus framework specific details, the drag handlers might look something like this:
+
 ```ts
 // i suggest against a barrel import if not using all features, but this is for demo purposes
 import {
@@ -410,11 +406,18 @@ Decos:
 - Split:
   - `.deco-split-new-frame` (new frame preview)
   - `.deco-split-edge` (edge preview)
+  - `.deco-split-error` (split preview in error state)
+- FrameDrag:
+  - `.deco-frame-drag` (frame drag ghost preview)
+  - `.deco-frame-drag-error` (frame drag preview in error state)
+  - `.deco-frame-drag-${type}-${side}` (e.g. `.deco-frame-drag-frame-left`, `.deco-frame-drag-zone-right`)
+
 
 State classes (so you can do stuff like `.request-split .drag-edge`)
 - `.dragging`
 - `.request-split`
 - `.request-close`
+- `.request-frame-drag`
 
 Several css variables are provided to help with sizing:
 - `--layoutHandleWidth`

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@witchcraft/layout",
   "configKey": "witchcraftLayout",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/runtime/components/FrameDragHandle.d.vue.ts

@@ -0,0 +1,15 @@
+type __VLS_Props = {
+    frameId: string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/FrameDragHandle.vue

@@ -0,0 +1,28 @@
+<template>
+<div
+	class="cursor-grabbing"
+	@pointerdown="handlePointerDown"
+>
+	<slot/>
+</div>
+</template>
+
+<script setup>
+import { inject, onBeforeUnmount } from "vue";
+import { dragContextInjectionKey } from "../drag/types.js";
+const props = defineProps({
+  frameId: { type: String, required: true }
+});
+const dragContext = inject(dragContextInjectionKey);
+if (!dragContext) {
+  throw new Error("FrameDragHandle must be used inside a LayoutWindow and drag context returned by useFrames must be injected.");
+}
+function handlePointerDown(e) {
+  e.preventDefault();
+  e.stopPropagation();
+  dragContext.dragStart(e, "frame", { frameId: props.frameId });
+}
+onBeforeUnmount(() => {
+  dragContext.cancel();
+});
+</script>

package/dist/runtime/components/FrameDragHandle.vue.d.ts

@@ -0,0 +1,15 @@
+type __VLS_Props = {
+    frameId: string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/LayoutDecos.d.vue.ts

@@ -1,8 +1,6 @@
-import { type CloseDeco, type LayoutFrames, type SplitDeco } from "../types/index.js";
+import type { LayoutShape } from "../types/index.js";
 type __VLS_Props = {
-    frames: LayoutFrames;
-    splitDecos: SplitDeco[];
-    closeDecos: CloseDeco[];
+    shapes: LayoutShape[];
 };
 declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/runtime/components/LayoutDecos.vue

@@ -1,33 +1,17 @@
 <template>
 <template
-	v-for="(deco) of splitDecos"
-	:key="deco.id"
+	v-for="(shape, i) of shapes"
+		:key="`${shape.type}-${i}`"
 >
 	<LayoutShapeSquare
-		class="
-				deco-split-new-frame
-				bg-blue-500/50
-			"
-		:css="getShapeSquareCss(deco.shapes.newFrame, `var(--layoutEdgeWidth,2px)`)"
+		v-if="shape.type === 'square'"
+		:css="getShapeSquareCss(shape.data, `var(--layoutEdgeWidth,2px)`)"
+		v-bind="shape.attrs ?? {}"
 	/>
 	<LayoutShapeSquare
-		class="
-			deco-split-edge
-			bg-red-500
-		"
-		:css="getVisualEdgeCss(deco.shapes.edge, { padLongAxis: `var(--layoutEdgeWidth,2px)` })"
-	/>
-</template>
-<template
-	v-for="deco of closeDecos"
-	:key="deco.id"
->
-	<LayoutShapeSquare
-		:class="`
-			${deco.force ? 'deco-close-force-frame' : 'deco-close-frame'}
-			bg-red-500/50
-		`"
-		:css="getShapeSquareCss(frames[deco.id], `var(--layoutEdgeWidth,2px)`)"
+		v-else-if="shape.type === 'edge'"
+		:css="getVisualEdgeCss(shape.data, { padLongAxis: 'var(--layoutEdgeWidth,2px)' })"
+		v-bind="shape.attrs ?? {}"
 	/>
 </template>
 </template>
@@ -36,10 +20,7 @@
 import LayoutShapeSquare from "./LayoutShapeSquare.vue";
 import { getShapeSquareCss } from "../helpers/getShapeSquareCss";
 import { getVisualEdgeCss } from "../helpers/getVisualEdgeCss";
-import {} from "../types/index.js";
-const props = defineProps({
-  frames: { type: Object, required: true },
-  splitDecos: { type: Array, required: true },
-  closeDecos: { type: Array, required: true }
+defineProps({
+  shapes: { type: Array, required: true }
 });
 </script>

package/dist/runtime/components/LayoutDecos.vue.d.ts

@@ -1,8 +1,6 @@
-import { type CloseDeco, type LayoutFrames, type SplitDeco } from "../types/index.js";
+import type { LayoutShape } from "../types/index.js";
 type __VLS_Props = {
-    frames: LayoutFrames;
-    splitDecos: SplitDeco[];
-    closeDecos: CloseDeco[];
+    shapes: LayoutShape[];
 };
 declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/runtime/components/LayoutEdges.d.vue.ts

@@ -1,11 +1,11 @@
-import { type Edge, type IntersectionEntry, type LayoutEdgesProps } from "../types/index.js";
+import type { Edge, IntersectionEntry, LayoutEdgesProps } from "../types/index.js";
 declare const _default: import("vue").DefineComponent<LayoutEdgesProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    dragStart: (e: PointerEvent, args_1: {
+    dragStart: (e: PointerEvent, type: "edge", opts: {
         edge?: Edge;
         intersection?: IntersectionEntry;
     }) => any;
 }, string, import("vue").PublicProps, Readonly<LayoutEdgesProps> & Readonly<{
-    onDragStart?: ((e: PointerEvent, args_1: {
+    onDragStart?: ((e: PointerEvent, type: "edge", opts: {
         edge?: Edge;
         intersection?: IntersectionEntry;
     }) => any) | undefined;

package/dist/runtime/components/LayoutEdges.vue

@@ -9,13 +9,12 @@
 		z-0
 		border-blue-500
 		border
-		rounded-md
 	`,
   $attrs.class
 )"
 	v-bind="{ ...$attrs, class: void 0 }"
 />
-	
+
 <template
 	v-for="css, i of cssDragEdges"
 	:key="i"
@@ -28,9 +27,9 @@
 			hover:cursor-pointer
 			[&:hover+.edge]:bg-blue-500/50
 		`)"
-		@pointerdown="emit('dragStart', $event, { edge: edges[i] })"
+		@pointerdown="emit('dragStart', $event, 'edge', { edge: edges[i] })"
 	/>
-	<LayoutShapeSquare
+		<LayoutShapeSquare
 		:css="css.thin"
 		:class="twMerge(`
 			pointer-events-none
@@ -49,7 +48,10 @@
 	v-for="css, i of cssDragEdge"
 	:key="i"
 />
-<template v-for="css, i of cssDragIntersections" :key="i">
+<template
+	v-for="css, i of cssDragIntersections"
+	:key="i"
+>
 	<LayoutShapeSquare
 		:css="css.thick"
 		:class="twMerge(
@@ -61,7 +63,7 @@
 		[&:hover+.intersection]:bg-blue-500/50
 		`
 )"
-		@pointerdown="emit('dragStart', $event, { intersection: wantedIntersections[i] })"
+		@pointerdown="emit('dragStart', $event, 'edge', { intersection: wantedIntersections[i] })"
 	/>
 	<LayoutShapeSquare
 		:css="css.thin"
@@ -86,8 +88,6 @@ import { getIntersectionsCss } from "../helpers/getIntersectionsCss.js";
 import { getShapeSquareCss } from "../helpers/getShapeSquareCss.js";
 import { getVisualEdgesCss } from "../helpers/getVisualEdgesCss.js";
 import { isEdgeEqual } from "../helpers/isEdgeEqual.js";
-import {
-} from "../types/index.js";
 const $attrs = useAttrs();
 defineOptions({
   inheritAttrs: false

package/dist/runtime/components/LayoutEdges.vue.d.ts

@@ -1,11 +1,11 @@
-import { type Edge, type IntersectionEntry, type LayoutEdgesProps } from "../types/index.js";
+import type { Edge, IntersectionEntry, LayoutEdgesProps } from "../types/index.js";
 declare const _default: import("vue").DefineComponent<LayoutEdgesProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    dragStart: (e: PointerEvent, args_1: {
+    dragStart: (e: PointerEvent, type: "edge", opts: {
         edge?: Edge;
         intersection?: IntersectionEntry;
     }) => any;
 }, string, import("vue").PublicProps, Readonly<LayoutEdgesProps> & Readonly<{
-    onDragStart?: ((e: PointerEvent, args_1: {
+    onDragStart?: ((e: PointerEvent, type: "edge", opts: {
         edge?: Edge;
         intersection?: IntersectionEntry;
     }) => any) | undefined;

package/dist/runtime/components/LayoutFrame.d.vue.ts

@@ -1,4 +1,4 @@
-import { type LayoutFrameProps } from "../types/index.js";
+import type { LayoutFrameProps } from "../types/index.js";
 declare var __VLS_8: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_8) => any;

package/dist/runtime/components/LayoutFrame.vue

@@ -33,7 +33,6 @@ defineOptions({
 import LayoutShapeSquare from "./LayoutShapeSquare.vue";
 import { getShapeSquareCss } from "../helpers/getShapeSquareCss";
 import { debugFrame } from "../layout/debugFrame.js";
-import {} from "../types/index.js";
 const emit = defineEmits(["focus"]);
 defineProps({
   frame: { type: Object, required: true },

package/dist/runtime/components/LayoutFrame.vue.d.ts

@@ -1,4 +1,4 @@
-import { type LayoutFrameProps } from "../types/index.js";
+import type { LayoutFrameProps } from "../types/index.js";
 declare var __VLS_8: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_8) => any;

package/dist/runtime/components/LayoutShapeSquare.d.vue.ts

@@ -1,9 +1,11 @@
+import type { HTMLAttributes } from "vue";
 import type { LayoutShapeSquareProps } from "../types/index.js";
+type __VLS_Props = LayoutShapeSquareProps & /** @vue-ignore */ HTMLAttributes;
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_component: import("vue").DefineComponent<LayoutShapeSquareProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<LayoutShapeSquareProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;
 type __VLS_WithSlots<T, S> = T & {

package/dist/runtime/components/LayoutShapeSquare.vue.d.ts

@@ -1,9 +1,11 @@
+import type { HTMLAttributes } from "vue";
 import type { LayoutShapeSquareProps } from "../types/index.js";
+type __VLS_Props = LayoutShapeSquareProps & /** @vue-ignore */ HTMLAttributes;
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_component: import("vue").DefineComponent<LayoutShapeSquareProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<LayoutShapeSquareProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;
 type __VLS_WithSlots<T, S> = T & {

package/dist/runtime/components/LayoutWindow.d.vue.ts

@@ -1,11 +1,15 @@
+import { DragActionHandler } from "../drag/DragActionHandler";
 import { type DragState, type IDragAction } from "../drag/types.js";
-import { type LayoutEdgesProps, type LayoutFrameProps, type LayoutWindow } from "../types/index.js";
+import type { LayoutEdgesProps, LayoutFrameProps, LayoutWindow } from "../types/index.js";
 type __VLS_Props = {
-    additionalDragActions?: IDragAction[];
-    splitKeyHandler?: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean;
-    closeKeyHandler?: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean;
-    usageInstructions?: Record<string, string | undefined>;
-    instructionsTeleportTo: string | undefined;
+    /** Custom drag action handlers. Falls back to default split/close/frame handlers if not provided. */
+    actionHandlers?: IDragAction[];
+    textHints?: {
+        text: string;
+        classes?: string;
+    }[];
+    textHintsTeleportTo: string | undefined;
+    ghostTeleportTo?: string;
     /**
      * You might need to temporarily disable updating the window size while transitioning, depending on your layout.
      *
@@ -23,9 +27,13 @@ type __VLS_PublicProps = __VLS_Props & {
 };
 declare var __VLS_9: any, __VLS_10: {
     frame: any;
-}, __VLS_22: {};
+}, __VLS_22: {}, __VLS_29: any, __VLS_30: {
+    id: any;
+};
 type __VLS_Slots = {} & {
     [K in NonNullable<typeof __VLS_9>]?: (props: typeof __VLS_10) => any;
+} & {
+    [K in NonNullable<typeof __VLS_29>]?: (props: typeof __VLS_30) => any;
 } & {
     'extra-decos'?: (props: typeof __VLS_22) => any;
 };
@@ -39,7 +47,9 @@ declare const __VLS_component: import("vue").DefineComponent<__VLS_PublicProps,
             x: number;
             y: number;
         } | undefined;
-        isDragging: boolean;
+        isDragging: false | "edge" | "frame";
+        showDragging: boolean;
+        draggingFrameId: string | undefined;
         draggingEdges: {
             startX: number;
             startY: number;
@@ -85,6 +95,7 @@ declare const __VLS_component: import("vue").DefineComponent<__VLS_PublicProps,
     }>;
     win: import("vue").ModelRef<import("../types/index.js").BaseLayoutWindow, string, import("../types/index.js").BaseLayoutWindow, import("../types/index.js").BaseLayoutWindow>;
     updateWindowSize: typeof updateWindowSize;
+    dragActionHandler: DragActionHandler<IDragAction[], import("@alanscodelog/utils").RecordFromArray<IDragAction[], "name">>;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:win": (value: import("../types/index.js").BaseLayoutWindow) => any;
 } & {
@@ -95,10 +106,13 @@ declare const __VLS_component: import("vue").DefineComponent<__VLS_PublicProps,
     onDragState?: ((value: DragState) => any) | undefined;
     "onUpdate:win"?: ((value: import("../types/index.js").BaseLayoutWindow) => any) | undefined;
 }>, {
-    additionalDragActions: IDragAction[];
-    splitKeyHandler: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean;
-    closeKeyHandler: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean;
-    usageInstructions: Record<string, string | undefined>;
+    actionHandlers: IDragAction[];
+    textHints: {
+        text: string;
+        classes?: string;
+    }[];
+    textHintsTeleportTo: string | undefined;
+    ghostTeleportTo: string;
     allowWindowSizeUpdate: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;