@meridian-ui/meridian 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# Meridian: A Design Framework for Malleable Overview-Detail Interfaces
+
+> Bryan Min and Haijun Xia. 2025. Meridian: A Design Framework for Malleable Overview-Detail Interfaces. In The 38th Annual ACM Symposium on User Interface Software and Technology (UIST ’25), September 28-October 1, 2025, Busan, Republic of Korea. ACM, New York, NY, USA, 13 pages. https://doi.org/10.1145/3746059.3747654
+
+This repository contains the Meridian developer package and two applications: a gallery of three example real-world ODIs and a no-code website builder.
+
+## Meridian Specification Types
+
+The Meridian specification is a JSON-based language for describing overview-detail interfaces.
+
+To view the full specification types, navigate to `src/spec/spec.ts`.
+
+To view the full specification for the three real-world examples from Section 5, navigate to the following files:
+
+- Example 1: `examples/gallery/src/views/d2-1/att.meridian.ts`
+- Example 2: `examples/gallery/src/views/d2-2/soccer.meridian.ts`
+- Example 3: `examples/gallery/src/views/d2-3/thesaurus.meridian.ts`
+
+To view the hotels specification from the video figure, navigate to: `examples/gallery/src/views/hotels/hotels.meridian.ts`
+
+## Gallery Website
+
+First, in the root directory, run
+
+```
+npm link meridian
+```
+
+(`meridian` being the name of the root directory)
+
+Then navigate to `examples/gallery`, and run:
+
+```
+npm link
+npm install
+```
+
+To run the gallery app, run:
+
+```
+npm run dev
+```
+
+## Website Builder Application
+
+Similar to running the gallery website, first should run
+
+```
+npm link meridian
+```
+
+Then navigate to `examples/web-builder`, and run:
+
+```
+npm link
+npm install
+```
+
+To run the gallery app, run:
+
+```
+npm run dev
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@meridian-ui/meridian",
+  "version": "1.0.0",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  
+  "scripts": {
+    "build": "tsc && npm run build:css",
+    "build:css": "npx tailwindcss -i ./src/styles/index.css -o ./dist/meridian.css --minify"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tailwindcss/postcss": "^4.0.15",
+    "@types/react-beautiful-dnd": "^13.1.8",
+    "@vis.gl/react-google-maps": "^1.x.x",
+    "dotenv": "^16.4.7",
+    "interactjs": "^1.10.27",
+    "react": "^18.x.x",
+    "react-beautiful-dnd": "^13.1.1",
+    "react-dom": "^18.x.x",
+    "sass": "^1.86.0",
+    "zustand": "^4.x.x"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.0",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.0",
+    "@svgr/webpack": "^8.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.21",
+    "postcss": "^8.5.3",
+    "rollup": "^4.24.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-postcss": "^4.0.2",
+    "storybook": "^8.3.5",
+    "tailwindcss": "^4.0.15",
+    "ts-loader": "^9.5.1",
+    "tslib": "^2.7.0",
+    "typescript": "^5.6.3",
+    "webpack": "^5.95.0",
+    "webpack-cli": "^5.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  }
+}

package/rollup.config.js

@@ -0,0 +1,51 @@
+import resolve from "@rollup/plugin-node-resolve";
+import commonjs from "@rollup/plugin-commonjs";
+import typescript from "@rollup/plugin-typescript";
+import dts from "rollup-plugin-dts";
+import terser from "@rollup/plugin-terser";
+import peerDepsExternal from "rollup-plugin-peer-deps-external";
+import postcss from "rollup-plugin-postcss";
+import tailwindcss from 'tailwindcss';
+import autoprefixer from 'autoprefixer';
+
+const packageJson = require("./package.json");
+
+export default [
+  {
+    input: "src/index.ts",
+    output: [
+      {
+        file: packageJson.main,
+        format: "cjs",
+        sourcemap: true,
+      },
+      {
+        file: packageJson.module,
+        format: "esm",
+        sourcemap: true,
+      },
+    ],
+    plugins: [
+      peerDepsExternal(),
+      resolve(),
+      commonjs(),
+      typescript({ tsconfig: "./tsconfig.json" }),
+      postcss({
+        plugins: [
+          tailwindcss(),
+          autoprefixer(),
+        ],
+        extract: 'src/styles/index.css',
+        modules: false,
+        inject: false,
+      }),
+      terser(),
+    ],
+    external: ["react", "react-dom"],
+  },
+  {
+    input: "src/index.ts",
+    output: [{ file: "dist/types.d.ts", format: "es" }],
+    plugins: [dts.default()],
+  },
+];

package/src/assets/add-tab.svg

@@ -0,0 +1,4 @@
+<svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M6 1L6 11" stroke="black" stroke-width="1.5" stroke-linecap="round"/>
+<path d="M1 6L11 6" stroke="black" stroke-width="1.5" stroke-linecap="round"/>
+</svg>

package/src/assets/chevron-right.svg

@@ -0,0 +1,4 @@
+<svg width="6" height="10" viewBox="0 0 6 10" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M1 9L5 5" stroke="black" stroke-width="1.5" stroke-linecap="round"/>
+<path d="M1 1L5 5" stroke="black" stroke-width="1.5" stroke-linecap="round"/>
+</svg>

package/src/assets/delete-tab.svg

@@ -0,0 +1,3 @@
+<svg width="8" height="8" viewBox="0 0 8 8" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M0.46967 6.46967C0.176777 6.76256 0.176777 7.23744 0.46967 7.53033C0.762563 7.82322 1.23744 7.82322 1.53033 7.53033L3.99902 5.06164L6.46967 7.53228C6.76256 7.82518 7.23744 7.82518 7.53033 7.53228C7.82322 7.23939 7.82322 6.76452 7.53033 6.47162L5.05968 4.00098L7.53033 1.53033C7.82322 1.23744 7.82322 0.762563 7.53033 0.46967C7.23744 0.176777 6.76256 0.176776 6.46967 0.46967L3.99902 2.94032L1.53033 0.471623C1.23744 0.17873 0.762563 0.17873 0.46967 0.471623C0.176777 0.764517 0.176777 1.23939 0.46967 1.53228L2.93836 4.00098L0.46967 6.46967Z" fill="black"/>
+</svg>

package/src/assets/dummy-data/skeleton.json

@@ -0,0 +1,42 @@
+[
+  {
+    "id": "0",
+    "name": ""
+  },
+  {
+    "id": "1",
+    "name": ""
+  },
+  {
+    "id": "2",
+    "name": ""
+  },
+  {
+    "id": "3",
+    "name": ""
+  },
+  {
+    "id": "4",
+    "name": ""
+  },
+  {
+    "id": "5",
+    "name": ""
+  },
+  {
+    "id": "6",
+    "name": ""
+  },
+  {
+    "id": "7",
+    "name": ""
+  },
+  {
+    "id": "8",
+    "name": ""
+  },
+  {
+    "id": "9",
+    "name": ""
+  }
+]

package/src/assets/dummy-data/skeleton.ts

@@ -0,0 +1,28 @@
+import { BindingItemType, DataBindingType, ODI } from "../../spec/spec";
+import { FetchedDataBindingType, FetchedODI } from "../../spec/spec.internal"
+
+// const 
+
+// const skeletonBinding: BindingItemType = {
+//   id: '.id',
+  
+// }
+
+const binding: BindingItemType = {
+  itemId: '.id',
+  attributes: [
+    { value: '.name', roles: ['thumbnail'] },
+    { value: '.name', roles: ['title'] },
+    { value: '.name', roles: ['subtitle'] },
+    { value: '.name', roles: ['description'] },
+  ]
+}
+
+const dataSources: DataBindingType[] = [
+  { binding: binding }
+];
+
+export const skeletonODI: ODI = {
+  dataBinding: dataSources,
+  overviews: [{ type: 'list', itemView: { type: 'profile-skeleton'} }],
+}

package/src/assets/meridian-toggle.svg

@@ -0,0 +1,4 @@
+<svg width="96" height="88" viewBox="0 0 96 88" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M38 34L38 28L32 28L16 28C10.4772 28 6 32.4771 6 38L6 72C6 77.5228 10.4771 82 16 82L28 82C33.5228 82 38 77.5228 38 72L38 34Z" stroke="black" stroke-width="12"/>
+<path d="M58 54L58 60L64 60L80 60C85.5229 60 90 55.5228 90 50L90 16C90 10.4771 85.5228 6 80 6L68 6C62.4772 6 58 10.4772 58 16L58 54Z" stroke="black" stroke-width="12"/>
+</svg>

package/src/components/attributes/attribute-price.tsx

@@ -0,0 +1,17 @@
+import { FetchedAttributeType } from '../../spec/spec.internal';
+import { isAttributeType } from '../../helpers/spec.helper';
+
+export const AttributePrice = ({
+  attribute,
+}: {
+  attribute: FetchedAttributeType;
+}) => {
+  if (!attribute || attribute.type !== 'price') return <></>;
+
+  // Check if attribute value is of the correct type
+  if (isAttributeType(attribute)) {
+    return <div>${attribute.value}</div>;
+  }
+
+  return <></>;
+};

package/src/components/detail-views/detail-basic.tsx

@@ -0,0 +1,121 @@
+import {
+  getAttributesByRole,
+  getAttributesWithoutRoles,
+} from '../../helpers/attribute.helper';
+import { DetailViewConfig, OpenViewIn, Role } from '../../spec/spec';
+import { FetchedItemType } from '../../spec/spec.internal';
+import { useODI } from '../../store/odi.store';
+import { Attribute } from '../../renderer/attribute';
+import './detail-view.scss';
+
+export interface DetailBasic extends DetailViewConfig {
+  type: 'basic';
+}
+
+export const DetailBasic = ({
+  // details,
+  item,
+}: {
+  // details: Detail[];
+  item: FetchedItemType | undefined;
+}) => {
+  const { odi, selectedItemEntity } = useODI();
+
+  if (!selectedItemEntity || !item) {
+    return <div></div>;
+  } else {
+    const unlabeledAttributes = getAttributesWithoutRoles(item, true) ?? [];
+
+    // console.log(item, getAttributesByRole(item, 'thumbnail'));
+    // console.log(odi, item);
+    return (
+      <div key={item.itemId} className="detail-view">
+        <div className="row g-3">
+          <div className="main-area">
+            <div className="thumbnail-area">
+              {/* Thumbnail */}
+              <Attribute
+                className="thumbnail"
+                options={selectedItemEntity.options}
+                attribute={getAttributesByRole(item, 'thumbnail')}
+              />
+              {/* Caption */}
+              <Attribute
+                options={selectedItemEntity.options}
+                attribute={getAttributesByRole(item, 'caption')}
+              />
+              {/* Badge */}
+              <Attribute
+                className="badge"
+                options={selectedItemEntity.options}
+                attribute={getAttributesByRole(item, 'badge')}
+              />
+            </div>
+            {/* Main Content Section */}
+            <div className="content-area">
+              <div className="header-area">
+                {['title', 'subtitle', 'description', 'key-attribute'].map(
+                  (role) =>
+                    getAttributesByRole(item, role as Role) && (
+                      <Attribute
+                        key={role}
+                        className={
+                          role === 'title'
+                            ? 'title'
+                            : role === 'subtitle'
+                            ? 'subtitle'
+                            : ''
+                        }
+                        options={selectedItemEntity.options}
+                        attribute={getAttributesByRole(item, role as Role)}
+                      />
+                    )
+                )}
+              </div>
+              {/* Tags */}
+              <div className="fl g-2 sm">
+                <Attribute
+                  options={selectedItemEntity.options}
+                  attribute={getAttributesByRole(item, 'tag')}
+                />
+              </div>
+              {/* Action Links */}
+              <div className="fl g-2 sm">
+                <Attribute
+                  options={selectedItemEntity.options}
+                  attribute={getAttributesByRole(item, 'action')}
+                />
+                <Attribute
+                  options={selectedItemEntity.options}
+                  attribute={getAttributesByRole(item, 'link')}
+                />
+              </div>
+            </div>
+            {/* Specs */}
+            <Attribute
+              options={selectedItemEntity.options}
+              attribute={getAttributesByRole(item, 'spec')}
+            />
+            {/* Footer */}
+            <Attribute
+              options={selectedItemEntity.options}
+              attribute={getAttributesByRole(item, 'footer')}
+            />
+          </div>
+        </div>
+        {/* Unlabeled Attributes (Supplementary Content) */}
+        {unlabeledAttributes.length > 0 && (
+          <div className="fl g-2">
+            {unlabeledAttributes.map((attr, idx) => (
+              <Attribute
+                key={idx}
+                options={selectedItemEntity.options}
+                attribute={attr}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+};

package/src/components/detail-views/detail-view.scss

@@ -0,0 +1,187 @@
+.detail-view {
+  padding: 32px;
+  container-type: inline-size;
+  margin-left: auto;
+  margin-right: auto;
+  width: inherit;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  align-items: flex-start;
+  padding: 32px;
+
+  @container (min-width: 768px) {
+    padding: 16px;
+    .main-area {
+      flex-direction: row;
+      .thumbnail {
+        height: 480px;
+      }
+    }
+  }
+
+  .main-area {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+
+    .thumbnail-area {
+      position: relative;
+      width: 100%;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      gap: 16px;
+      .thumbnail {
+        max-width: 400px;
+        height: 200px;
+        border-radius: 16px;
+        overflow: hidden;
+      }
+    }
+  }
+
+  .content-area {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    .header-area {
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+      .title {
+        font-size: 24px;
+      }
+      .subtitle {
+        font-size: 16px;
+        color: #6b7280;
+      }
+    }
+  }
+
+
+  .badge {
+    position: absolute;
+    top: -16px;
+    left: -16px;
+    z-index: 100;
+    background-color: white;
+    border-radius: 12px;
+    padding: 2px 8px;
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+  }
+
+  .abs-float {
+    display: absolute;
+    top: 0;
+    left: 0;
+    z-index: 70;
+  }
+
+  .fl {
+    display: flex;
+  }
+
+  .col {
+    display: flex;
+    flex-direction: column;
+  }
+  .row {
+    display: flex;
+    flex-direction: row;
+  }
+  .j-c {
+    justify-content: center;
+  }
+  .i-c {
+    align-items: center;
+  }
+  .g-1 {
+    gap: 4px;
+  }
+  .g-2 {
+    gap: 8px;
+  }
+  .g-3 {
+    gap: 12px;
+  }
+
+  .lg {
+    font-size: 18px;
+  }
+  .md {
+    font-size: 16px;
+  }
+  .sm {
+    font-size: 14px;
+  }
+
+  .f-m {
+    font-weight: 500;
+  }
+  .f-b {
+    font-weight: 700;
+  }
+}
+
+
+.item-profile {
+  position: relative;
+  display: flex;
+  gap: 16px;
+  padding: 8px;
+
+  
+  .content-area {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    .header-area {
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+      .column {
+        display: flex;
+        flex-direction: column;
+        .title {
+          font-size: 18px;
+        }
+        .subtitle {
+          font-size: 14px;
+          color: #6b7280;
+        }
+      }
+    }
+  }
+
+}
+
+.item-pin {
+  width: fit-content;
+  position: relative;
+  display: flex;
+  gap: 16px;
+  padding: 2px 6px;
+  justify-content: center;
+  align-items: center;
+}
+
+.item-compact {
+  width: 100%;
+  border: 1px solid #e5e7eb;
+  border-radius: 6px;
+  padding: 4px;
+  display: flex;
+  flex-direction: row;
+  gap: 12px;
+  justify-content: start;
+  align-items: center;
+  .image {
+    width: 60px;
+    height: 60px;
+    overflow: hidden;
+  }
+  .non-image {
+    max-width: 240px;
+  }
+}

package/src/components/item-views/item-compact.tsx

@@ -0,0 +1,72 @@
+import {
+  attributeInScope,
+  getAttributesByHasRole,
+  getAttributesWithoutRoles,
+} from '../../helpers/attribute.helper';
+import { isAttributeType } from '../../helpers/spec.helper';
+import { ItemViewConfig } from '../../spec/spec';
+import {
+  FetchedAttributeType,
+  FetchedItemType,
+  ViewOptions,
+} from '../../spec/spec.internal';
+import { Attribute } from '../../renderer/attribute';
+import './item-view.scss';
+export interface ItemCompactType extends ItemViewConfig {
+  type: 'compact';
+}
+
+export const ItemCompact = ({
+  options,
+  item,
+  index,
+  className,
+  style,
+}: {
+  options: ViewOptions;
+  item: FetchedItemType | undefined;
+  index: number;
+  className?: string;
+  style?: React.CSSProperties;
+}) => {
+  if (!item) return <></>;
+
+  const shown = options.overview.shownAttributes;
+  const labeledAttributes = item.attributes
+    .flatMap((a) => getAttributesByHasRole(a, true))
+    .filter((a) => attributeInScope(shown, a));
+
+  const unlabeledAttributes = getAttributesWithoutRoles(item) ?? [];
+
+  const sliceMax = Math.min(0, 4 - labeledAttributes.length);
+
+  const CompactAttribute = ({
+    attribute,
+  }: {
+    attribute: FetchedAttributeType;
+  }) => (
+    <Attribute
+      className={`sm
+  ${
+    isAttributeType(attribute) && attribute.type === 'image'
+      ? 'image'
+      : 'non-image'
+  }`}
+      options={options}
+      attribute={attribute}
+    />
+  );
+
+  console.log(unlabeledAttributes);
+
+  return (
+    <div className={`item-compact ${className}`} style={style}>
+      {labeledAttributes.map((attribute) => (
+        <CompactAttribute key={attribute?.id} attribute={attribute} />
+      ))}
+      {unlabeledAttributes.slice(0, sliceMax).map((attribute) => (
+        <CompactAttribute key={attribute?.id} attribute={attribute} />
+      ))}
+    </div>
+  );
+};