@dignite/ng.site 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @dignite/ng.site
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Angular library for Dignite Site's admin UI: routes, components, and services under `src/`
+(imported as `@dignite/ng.site`), plus `provideSite()` and friends under `config/`
+(imported as `@dignite/ng.site/config`).
+
+## Installing
+
+```bash
+npm install @dignite/ng.site
+```
+
+(Pre-release builds are published to GitHub Packages as `@dignite-projects/ng.site`; see the root
+[README](../../README.md) / `angular/.npmrc` for the registry setup, and alias the dependency:
+`"@dignite/ng.site": "npm:@dignite-projects/ng.site@<version>"`.)
+
+### CKEditor dependency and the file library
+
+`provideSite()` (from `@dignite/ng.site/config`) unconditionally registers the CKEditor field type and
+Site's own field types - it's not optional, skipping one makes `FieldTypeResolver.get(...)` throw and the
+content editor fails to render entirely. So this package declares `@dignite/ng.flex-fields-ckeditor` as
+its own `dependency`, not a `peerDependency` - and from `10.0.0-rc.13` that adapter in turn declares
+everything *it* needs (`@ckeditor/ckeditor5-angular`, `ckeditor5`, `marked`) as its own dependencies
+rather than peers. `npm install @dignite/ng.site` (see "Installing" above) is the whole install; there's
+nothing to add by hand.
+
+The file picker, the file field type (registration key `FileExplorer`) and the SEO share-image picker
+are this package's own (`src/lib/files`, `src/lib/field-types/file`) and talk to Site's admin API
+(`apiName: 'SiteAdmin'`) - there is no separate file-picker package to install any more, and no extra
+entry to keep in `environment.apis`. `provideSite()` also registers `SiteCKEditorUploadProvider` as the
+`CKEDITOR_UPLOAD_PROVIDER` (which needs `@dignite/ng.flex-fields-ckeditor >= 10.0.0-rc.25`), so an image
+inserted into a CKEditor field is uploaded into Site's file library. See `docs/site-files.md`.
+
+That `>= 10.0.0-rc.13` floor is load-bearing, not cosmetic. Below `rc.12` those packages were
+the adapters' `peerDependencies`, and every ABP 10.7 + Angular 22 host installs with
+`--legacy-peer-deps` (`@abp/ng.theme.shared` pins `@swimlane/ngx-datatable@~22`, whose own Angular
+peer range stops at 20), under which npm does not install peers at all. Loosening the floor back
+below `rc.12` would silently reintroduce four unresolvable imports - discovered at the consuming
+app's build, with nothing in `npm install` to warn about them.
+
+During the pre-release (GitHub Packages) channel you do not need to separately alias the
+`@dignite/*` packages this one depends on (`@dignite/ng.flex-fields` and the adapter above) -
+the release workflow's scope-swap step rewrites every `@dignite/*` entry under `dependencies` in
+the published package.json to the same alias form used for `@dignite/ng.site` itself above. That
+step never covered `peerDependencies`, which is exactly why the old manual alias instruction lived
+here.
+
+### Required global styles (ng-zorro-antd)
+
+`@dignite/ng.site` builds several fields on `ng-zorro-antd` (`nz-tree`, `nz-tree-select`, `nz-select`,
+`nz-autocomplete` - pulled in directly or via the `@dignite/ng.flex-fields` dependency). These
+components render their dropdown/panel content through Angular CDK's overlay, which attaches
+directly to `<body>` outside this library's view tree - so they can only be styled with global CSS,
+never with the scoped component styles an Angular library ships to consumers.
+
+That makes this a hard limitation, not an oversight: ng-packagr has no mechanism to add entries to
+a *consuming application's* `angular.json` (or global style bundle), so every app that installs
+`@dignite/ng.site` has to register these stylesheets itself. Skipping this doesn't break the
+build - it silently leaves the affected controls unstyled (e.g. a tree-select panel with no
+background or positioning). This has already caught out two separate hosts (this repo's own `Host`
+app and the `cloud` project both needed the identical fix) - budget for it on every new one.
+
+Add to the host app's `angular.json`, in `projects.<app>.architect.build.options.styles`:
+
+```jsonc
+{ "input": "node_modules/ng-zorro-antd/tree/style/index.min.css", "inject": false, "bundleName": "ng-zorro-antd-tree" },
+{ "input": "node_modules/ng-zorro-antd/tree-select/style/index.min.css", "inject": true, "bundleName": "ng-zorro-antd-tree-select" },
+{ "input": "node_modules/ng-zorro-antd/select/style/index.min.css", "inject": false, "bundleName": "ng-zorro-antd-select" },
+{ "input": "node_modules/ng-zorro-antd/auto-complete/style/index.min.css", "inject": true, "bundleName": "ng-zorro-antd-auto-complete" },
+{ "input": "node_modules/ckeditor5/dist/ckeditor5.css", "inject": false, "bundleName": "ckeditor5" }
+```
+
+The three `inject: false` entries are fetched at runtime by fixed file name - `ng-zorro-antd-tree.css`
+by ABP's `<abp-tree>` (which flex-fields' `Tree` field types and this library's content-list page
+filter render; this is the entry ABP's own 7.0 migration guide prescribes), `ng-zorro-antd-select.css`
+by `@dignite/ng.flex-fields`' `Select`
+controls and by this library's field arrangement picker, and `ckeditor5.css` by
+`@dignite/ng.flex-fields-ckeditor`, which `@dignite/ng.site/config` always registers.
+`inject: false` is what keeps those names literal: under the production `outputHashing: "all"` an
+injected entry is emitted under a content hash, so the fetch 404s. For the two flex-fields bundles
+that costs a console error - and for `ckeditor5`, an editor that renders as blank space. For
+`ng-zorro-antd-tree` it is worse: `abp-tree` loads with no retry limit, and ABP's `LazyLoadService`
+removes and re-inserts the failed `<link>` on every attempt, so an injected tree entry turns into an
+unbroken stream of 404 requests for as long as a tree is on screen. See the "Styles" section of the
+`@dignite/ng.flex-fields` and `@dignite/ng.flex-fields-ckeditor` READMEs (>= 10.0.0-rc.17).
+
+If the host doesn't wire global styles through `angular.json`, `@import` the two injected paths
+from its root stylesheet instead; the three fetched by name still need their `angular.json` entries.
+
+`ng-zorro-antd` itself is declared as a direct `dependency` of `@dignite/ng.site` (not a peer), the
+same way `@angular/cdk` is: every consumer needs it unconditionally, there's no opt-out the way
+there is for the CKEditor/File Explorer field types, so there's no reason to push the install step
+onto the host. Both stay on their 21 line on an Angular 22 host, because that is what ABP 10.7 brings:
+`@abp/ng.components` 10.7.0 depends on `ng-zorro-antd` `~21.3.1`, and `ng-zorro-antd` 21.3 depends on
+`@angular/cdk` `^21`. They are declared as `~21.3.1` and `~21.2.0` so a host that declares the same ranges
+gets one copy of each; a range the ABP copy does not satisfy (`ng-zorro-antd` 22 or `@angular/cdk` 22) is
+installed beside it, giving two module-scoped `NZ_CONFIG` / `NzConfigService` tokens.
+`@swimlane/ngx-datatable` is different - it's a `peerDependency` here because
+`@abp/ng.theme.shared` already guarantees every ABP host has it.
+
+This list only covers what `@dignite/ng.site` and `@dignite/ng.flex-fields` import as of this writing.
+Re-derive it before trusting it on a new `ng-zorro-antd` version, or after either package adds a new
+field type:
+
+```bash
+grep -rohE "ng-zorro-antd/[a-z-]+" node_modules/@dignite/ng.site node_modules/@dignite/ng.flex-fields | sort -u
+```
+
+## Code scaffolding
+
+Run `ng generate component component-name --project site` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project site`.
+> Note: Don't forget to add `--project site` or else it will be added to the default project in your `angular.json` file.
+
+## Build
+
+Run `ng build site` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Running unit tests
+
+Run `ng test site` to execute the unit tests via [Vitest](https://vitest.dev).
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

package/fesm2022/dignite-ng.site-config.mjs

@@ -0,0 +1,87 @@
+import { RoutesService } from '@abp/ng.core';
+import { provideFlexFields } from '@dignite/ng.flex-fields';
+import { CKEDITOR_UPLOAD_PROVIDER, CKEDITOR_CONFIG_CONTRIBUTORS, CKEDITOR_DISPLAY_CONTRIBUTORS, provideCKEditorFieldType } from '@dignite/ng.flex-fields-ckeditor';
+import { SiteCKEditorUploadProvider, siteCKEditorConfigContributor, siteCKEditorDisplayContributor, SEO_FIELD_TYPE, CONTENT_FIELD_TYPE, FILE_FIELD_TYPE } from '@dignite/ng.site';
+import { provideAppInitializer, inject, makeEnvironmentProviders } from '@angular/core';
+
+const SITE_ROUTE_PROVIDERS = [
+    provideAppInitializer(() => {
+        configureRoutes();
+    }),
+];
+function configureRoutes() {
+    const routesService = inject(RoutesService);
+    routesService.add([
+        {
+            path: '/site',
+            name: "Site::Menu:Site" /* eSiteRouteNames.Site */,
+            iconClass: 'fas fa-globe',
+            layout: "application" /* eLayoutType.application */,
+            order: 3,
+            requiredPolicy: 'SiteAdmin.Pages || SiteAdmin.ContentTypes || SiteAdmin.Fields || SiteAdmin.Contents',
+        },
+        {
+            path: '/site/contents',
+            name: "Site::Menu:Contents" /* eSiteRouteNames.Contents */,
+            parentName: "Site::Menu:Site" /* eSiteRouteNames.Site */,
+            iconClass: 'fas fa-file-lines',
+            layout: "application" /* eLayoutType.application */,
+            order: 1,
+            requiredPolicy: 'SiteAdmin.Contents',
+        },
+        {
+            path: '/site/pages',
+            name: "Site::Menu:Pages" /* eSiteRouteNames.Pages */,
+            parentName: "Site::Menu:Site" /* eSiteRouteNames.Site */,
+            iconClass: 'fas fa-file-code',
+            layout: "application" /* eLayoutType.application */,
+            order: 2,
+            requiredPolicy: 'SiteAdmin.Pages',
+        },
+        {
+            path: '/site/fields',
+            name: "Site::Menu:Fields" /* eSiteRouteNames.Fields */,
+            parentName: "Site::Menu:Site" /* eSiteRouteNames.Site */,
+            iconClass: 'fas fa-list-check',
+            layout: "application" /* eLayoutType.application */,
+            order: 3,
+            requiredPolicy: 'SiteAdmin.Fields',
+        },
+    ]);
+    // Content types have no menu entry: they belong to a page, and are reached from the Pages list.
+}
+const SITE_PROVIDERS = [
+    ...SITE_ROUTE_PROVIDERS,
+    // The six built-ins (Matrix/Table among them as of flex-fields 10.0.0-rc.16, via
+    // provideFlexFields()'s own BUILT_IN_FIELD_TYPES - they used to be Site's own MATRIX_FIELD_TYPE/
+    // TABLE_FIELD_TYPE, registered explicitly here, until flex-fields shipped them as kernel built-ins)
+    // plus Site's own `Seo`, `Content` and file (GitHub issue #42) types (GitHub issue #49). `FieldTypeResolver` is root-provided and reads the registry once when first
+    // injected, so this has to happen at application-config level - registering from inside the
+    // lazy-loaded Site routes would come too late for a resolver already constructed.
+    provideFlexFields(SEO_FIELD_TYPE, CONTENT_FIELD_TYPE, FILE_FIELD_TYPE),
+    // The CKEditor field type (GitHub issue #43). Unlike the server, where DependsOn plus DI discovery is
+    // enough (总体设计 §8.2), the client has no equivalent - each field type's control/config/view trio has
+    // to be registered explicitly or FieldTypeResolver.get(...) throws and the content editor breaks on
+    // first use, the same failure mode SEO_FIELD_TYPE's own comment warns about.
+    provideCKEditorFieldType(),
+    // Inline images in a CKEditor field go into Site's file library (the field's CKEditor.ImagesContainerName,
+    // normally images) and are embedded by their public address. Without a provider the editor shows
+    // no upload button at all.
+    { provide: CKEDITOR_UPLOAD_PROVIDER, useExisting: SiteCKEditorUploadProvider },
+    // Those addresses are stored relative (/api/site-public/files/...); the editor shows them from the
+    // SiteAdmin API's host, in its editing view only - getData(), and so what is saved, stays relative.
+    { provide: CKEDITOR_CONFIG_CONTRIBUTORS, multi: true, useFactory: siteCKEditorConfigContributor },
+    // The read-only view (ff-ckeditor-view: a content list cell) has no editor to convert in, so its HTML gets
+    // the same host in front of those addresses before it is rendered; nothing is saved from there.
+    { provide: CKEDITOR_DISPLAY_CONTRIBUTORS, multi: true, useFactory: siteCKEditorDisplayContributor },
+];
+function provideSite() {
+    return makeEnvironmentProviders(SITE_PROVIDERS);
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { SITE_ROUTE_PROVIDERS, configureRoutes, provideSite };
+//# sourceMappingURL=dignite-ng.site-config.mjs.map

package/fesm2022/dignite-ng.site-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dignite-ng.site-config.mjs","sources":["../../../projects/site/config/src/providers/route.provider.ts","../../../projects/site/config/src/dignite-ng.site-config.ts"],"sourcesContent":["import { eLayoutType, RoutesService } from '@abp/ng.core';\nimport { provideFlexFields } from '@dignite/ng.flex-fields';\nimport {\n  CKEDITOR_CONFIG_CONTRIBUTORS,\n  CKEDITOR_DISPLAY_CONTRIBUTORS,\n  CKEDITOR_UPLOAD_PROVIDER,\n  provideCKEditorFieldType,\n} from '@dignite/ng.flex-fields-ckeditor';\nimport {\n  CONTENT_FIELD_TYPE,\n  FILE_FIELD_TYPE,\n  SEO_FIELD_TYPE,\n  SiteCKEditorUploadProvider,\n  siteCKEditorConfigContributor,\n  siteCKEditorDisplayContributor,\n} from '@dignite/ng.site';\nimport {\n  EnvironmentProviders,\n  inject,\n  makeEnvironmentProviders,\n  Provider,\n  provideAppInitializer,\n} from '@angular/core';\nimport { eSiteRouteNames } from '../enums/route-names';\n\nexport const SITE_ROUTE_PROVIDERS = [\n  provideAppInitializer(() => {\n    configureRoutes();\n  }),\n];\n\nexport function configureRoutes() {\n  const routesService = inject(RoutesService);\n  routesService.add([\n    {\n      path: '/site',\n      name: eSiteRouteNames.Site,\n      iconClass: 'fas fa-globe',\n      layout: eLayoutType.application,\n      order: 3,\n      requiredPolicy:\n        'SiteAdmin.Pages || SiteAdmin.ContentTypes || SiteAdmin.Fields || SiteAdmin.Contents',\n    },\n    {\n      path: '/site/contents',\n      name: eSiteRouteNames.Contents,\n      parentName: eSiteRouteNames.Site,\n      iconClass: 'fas fa-file-lines',\n      layout: eLayoutType.application,\n      order: 1,\n      requiredPolicy: 'SiteAdmin.Contents',\n    },\n    {\n      path: '/site/pages',\n      name: eSiteRouteNames.Pages,\n      parentName: eSiteRouteNames.Site,\n      iconClass: 'fas fa-file-code',\n      layout: eLayoutType.application,\n      order: 2,\n      requiredPolicy: 'SiteAdmin.Pages',\n    },\n    {\n      path: '/site/fields',\n      name: eSiteRouteNames.Fields,\n      parentName: eSiteRouteNames.Site,\n      iconClass: 'fas fa-list-check',\n      layout: eLayoutType.application,\n      order: 3,\n      requiredPolicy: 'SiteAdmin.Fields',\n    },\n  ]);\n\n  // Content types have no menu entry: they belong to a page, and are reached from the Pages list.\n}\n\nconst SITE_PROVIDERS: (EnvironmentProviders | Provider)[] = [\n  ...SITE_ROUTE_PROVIDERS,\n  // The six built-ins (Matrix/Table among them as of flex-fields 10.0.0-rc.16, via\n  // provideFlexFields()'s own BUILT_IN_FIELD_TYPES - they used to be Site's own MATRIX_FIELD_TYPE/\n  // TABLE_FIELD_TYPE, registered explicitly here, until flex-fields shipped them as kernel built-ins)\n  // plus Site's own `Seo`, `Content` and file (GitHub issue #42) types (GitHub issue #49). `FieldTypeResolver` is root-provided and reads the registry once when first\n  // injected, so this has to happen at application-config level - registering from inside the\n  // lazy-loaded Site routes would come too late for a resolver already constructed.\n  provideFlexFields(SEO_FIELD_TYPE, CONTENT_FIELD_TYPE, FILE_FIELD_TYPE),\n  // The CKEditor field type (GitHub issue #43). Unlike the server, where DependsOn plus DI discovery is\n  // enough (总体设计 §8.2), the client has no equivalent - each field type's control/config/view trio has\n  // to be registered explicitly or FieldTypeResolver.get(...) throws and the content editor breaks on\n  // first use, the same failure mode SEO_FIELD_TYPE's own comment warns about.\n  provideCKEditorFieldType(),\n  // Inline images in a CKEditor field go into Site's file library (the field's CKEditor.ImagesContainerName,\n  // normally images) and are embedded by their public address. Without a provider the editor shows\n  // no upload button at all.\n  { provide: CKEDITOR_UPLOAD_PROVIDER, useExisting: SiteCKEditorUploadProvider },\n  // Those addresses are stored relative (/api/site-public/files/...); the editor shows them from the\n  // SiteAdmin API's host, in its editing view only - getData(), and so what is saved, stays relative.\n  { provide: CKEDITOR_CONFIG_CONTRIBUTORS, multi: true, useFactory: siteCKEditorConfigContributor },\n  // The read-only view (ff-ckeditor-view: a content list cell) has no editor to convert in, so its HTML gets\n  // the same host in front of those addresses before it is rendered; nothing is saved from there.\n  { provide: CKEDITOR_DISPLAY_CONTRIBUTORS, multi: true, useFactory: siteCKEditorDisplayContributor },\n];\n\nexport function provideSite() {\n  return makeEnvironmentProviders(SITE_PROVIDERS);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;;;;;AAyBO,MAAM,oBAAoB,GAAG;IAClC,qBAAqB,CAAC,MAAK;AACzB,QAAA,eAAe,EAAE;AACnB,IAAA,CAAC,CAAC;;SAGY,eAAe,GAAA;AAC7B,IAAA,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC3C,aAAa,CAAC,GAAG,CAAC;AAChB,QAAA;AACE,YAAA,IAAI,EAAE,OAAO;AACb,YAAA,IAAI,EAAA,iBAAA;AACJ,YAAA,SAAS,EAAE,cAAc;AACzB,YAAA,MAAM,EAAA,aAAA;AACN,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,cAAc,EACZ,qFAAqF;AACxF,SAAA;AACD,QAAA;AACE,YAAA,IAAI,EAAE,gBAAgB;AACtB,YAAA,IAAI,EAAA,qBAAA;AACJ,YAAA,UAAU,EAAA,iBAAA;AACV,YAAA,SAAS,EAAE,mBAAmB;AAC9B,YAAA,MAAM,EAAA,aAAA;AACN,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,cAAc,EAAE,oBAAoB;AACrC,SAAA;AACD,QAAA;AACE,YAAA,IAAI,EAAE,aAAa;AACnB,YAAA,IAAI,EAAA,kBAAA;AACJ,YAAA,UAAU,EAAA,iBAAA;AACV,YAAA,SAAS,EAAE,kBAAkB;AAC7B,YAAA,MAAM,EAAA,aAAA;AACN,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,cAAc,EAAE,iBAAiB;AAClC,SAAA;AACD,QAAA;AACE,YAAA,IAAI,EAAE,cAAc;AACpB,YAAA,IAAI,EAAA,mBAAA;AACJ,YAAA,UAAU,EAAA,iBAAA;AACV,YAAA,SAAS,EAAE,mBAAmB;AAC9B,YAAA,MAAM,EAAA,aAAA;AACN,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,cAAc,EAAE,kBAAkB;AACnC,SAAA;AACF,KAAA,CAAC;;AAGJ;AAEA,MAAM,cAAc,GAAwC;AAC1D,IAAA,GAAG,oBAAoB;;;;;;;AAOvB,IAAA,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,EAAE,eAAe,CAAC;;;;;AAKtE,IAAA,wBAAwB,EAAE;;;;AAI1B,IAAA,EAAE,OAAO,EAAE,wBAAwB,EAAE,WAAW,EAAE,0BAA0B,EAAE;;;IAG9E,EAAE,OAAO,EAAE,4BAA4B,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,6BAA6B,EAAE;;;IAGjG,EAAE,OAAO,EAAE,6BAA6B,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,8BAA8B,EAAE;CACpG;SAEe,WAAW,GAAA;AACzB,IAAA,OAAO,wBAAwB,CAAC,cAAc,CAAC;AACjD;;ACvGA;;AAEG;;;;"}