spiderly 19.10.1 → 19.11.0

package/agent/docs/angular-customization/index.md

@@ -363,6 +363,8 @@ menu: SpiderlyMenuItem[] = [
 </spiderly-layout>
 ```
 
+The side menu's desktop collapse state persists automatically (localStorage key `spiderly-layout:menu-desktop-inactive`), so the sidebar stays collapsed/expanded across reloads.
+
 ## Validation
 
 ### ValidatorAbstractService

package/agent/docs/entity-design/index.md

@@ -25,6 +25,23 @@ namespace Foo.Business.Entities
 
 Hand-written DTOs use `[SpiderlyDTO]`. Generated DTOs (`{Entity}DTO`, `{Entity}SaveBodyDTO`, `{Entity}MainUIFormDTO`) need no marker. The `spiderly add-new-entity` CLI emits `[SpiderlyEntity]` automatically.
 
+### Generated DTO nullability
+
+`[Required]` decides it for **reference types only**:
+
+| Entity property           | Generated DTO property                                    |
+| ------------------------- | --------------------------------------------------------- |
+| `[Required] string Name`  | `string Name { get; set; } = null!;`                       |
+| `string Slug`             | `string? Slug` (bare `string` for a nullable-oblivious app) |
+| `[Required] int Quantity` | `int? Quantity` — value types stay nullable, see below      |
+| `int Stock`               | `int? Stock`                                                |
+| any navigation            | `long? CategoryId` + `string? CategoryDisplayName`          |
+| any collection            | unchanged, with `= new()`                                   |
+
+**Value types stay nullable even under `[Required]`, deliberately.** A generated `{Entity}DTO` serves four roles at once: response shape, request shape, the Angular form model (an empty numeric input posts `null`), and the sparse placeholder carrier for `[ComplexManyToManyList]` grids, where an all-null row *is* the "no record" sentinel. The last two need `null` to be representable, and `int` cannot hold it. Reference types are safe to tighten because, with `RespectNullableAnnotations` off, a non-nullable `string` still accepts `null` at runtime — `= null!` is an assertion for the compiler and for humans, not a runtime constraint.
+
+**The C# annotation is invisible to the OpenAPI spec unless the app opts in** with `spiderly.AddSwagger(options => options.SupportNonNullableReferenceTypes())`. Not on by default: it narrows the published contract (members become `required`), which regenerates every consumer's typed client — schedule it as its own deploy. `spiderly init` scaffolds it, since a new app has no consumers yet. `AddSwagger`'s callback runs after Spiderly's defaults and is the seam for any other Swashbuckle option too.
+
 ## Base Classes
 
 | Base Class          | Use When               | Generated                                        |
@@ -67,7 +84,7 @@ public virtual Brand Brand { get; set; }
 ### When to use it
 
 - **Hand-written save/sync code** that builds the entity directly (`new Order { BrandId = id, ... }`) — skips the `FindAsync` + navigation-attach roundtrip that the naive pattern requires
-- **Hot read paths** with `ProjectToDTO` — the mapper emits `x.BrandId` instead of the `EF.Property<long>(x, "BrandId")` workaround for [EF Core #15826](https://github.com/dotnet/efcore/issues/15826), which otherwise still forces a JOIN in some queries
+- **Hot read paths** in mapper projections — the mapper emits `x.BrandId` instead of the `EF.Property<long>(x, "BrandId")` workaround for [EF Core #15826](https://github.com/dotnet/efcore/issues/15826), which otherwise still forces a JOIN in some queries
 
 ### Rules
 
@@ -298,7 +315,6 @@ The complete list of every Spiderly attribute and its valid target is generated
 | `[ExcludeServiceMethodsFromGeneration]` | Property       | Skip generated service methods (implement custom logic)                                              |
 | `[GreaterThanOrEqualTo(N)]`             | Property       | Numeric minimum validation                                                                           |
 | `[Email]`                               | Property       | Email format validation                                                                              |
-| `[ProjectToDTO(".Map(...)")]`           | Class          | Custom Mapster projection                                                                            |
 | `[GenerateCommaSeparatedDisplayName]`   | Property       | Add comma-separated display names to DTO                                                             |
 | `[ComplexManyToManyList]`               | Property       | Editable list UI for complex M2M junction (small sets only)                                          |
 | `[ComplexManyToManyReadonlyTable]`      | Property       | Read-only table for complex M2M junction                                                             |

package/agent/docs/entity-design/references/attributes.generated.md

@@ -27,7 +27,6 @@
 | `[M2MWithMany]` | Property | Marks a property in a many-to-many (M2M) relationship. |
 | `[MaxFileSize]` | Property | Specifies the maximum allowed file size (in bytes) for a blob property. When not applied, the file upload defaults to 20 MB (20,000,000 bytes). Use this attribute alongside any StorageAttribute subclass for file uploads. |
 | `[Output]` | All | Specifies the output configuration for the Source Generator. Note: This is a temporary solution and may be replaced in future versions. |
-| `[ProjectToDTO]` | Class | Specifies custom mapping configuration when projecting an entity to its DTO. |
 | `[ReadOnly]` | Property | Marks a property as server-owned: the client may read it, but can never write it (mirrors OpenAPI readOnly). The property stays in the read {Entity}DTO — so it's still returned by GET endpoints and shown in the list table — but the generator closes the write path for it: no inbound FluentValidation rule is emitted, and the generated DTO→entity Mapster config .Ignore()s it, so a crafted payload can't tamper with it. It also gets no editable control in the generated details form. Use for values only backend code assigns — usage counters, denormalized aggregates, computed timestamps. Combine with [Required] to document the non-null DB column without generating an unsatisfiable inbound rule (the form never sends it). This differs from [UIDoNotGenerate] (hidden from the form but still writable and validated) and [ExcludeFromDTO] (dropped from every DTO, unreadable). |
 | `[S3PrivateStorage]` | Property | Routes upload/delete operations for the decorated string property through S3PrivateStorageService. The column stores an opaque S3 key; access is expected to be mediated via signed URLs or a backend proxy rather than direct CDN retrieval. Intended for files that contain personal or compliance-sensitive data (warranty receipts, ID documents, customer-uploaded invoices). |
 | `[S3PublicStorage]` | Property | Routes upload/delete operations for the decorated string property through S3PublicStorageService. The bucket is configured for public access and the column stores a fully-qualified CDN URL; objects are uploaded with Cache-Control: public, max-age=31536000, immutable. |

package/agent/docs/mapper-customization/index.md

@@ -1,6 +1,6 @@
 ---
 name: mapper-customization
-description: Customize Spiderly-generated Mapster mappers. Use when overriding DTO-to-entity or entity-to-DTO mapping, adding computed fields to DTOs, customizing query projections, or using the ProjectToDTO attribute.
+description: Customize Spiderly-generated Mapster mappers. Use when overriding DTO-to-entity or entity-to-DTO mapping, adding computed fields to DTOs, customizing query projections, or implementing Customize* partial mapper hooks.
 ---
 
 # Mapper Customization
@@ -35,48 +35,71 @@ public static TypeAdapterConfig CartToDTOConfig()
 }
 ```
 
-## `[ProjectToDTO]` — Inline Custom Mappings
+## `Customize*` Partial Hooks — Add Mappings in Real C#
 
-Add custom mappings to the projection method without overriding it. Applied to the **entity class** (not properties). `AllowMultiple = true`.
+Every generated config method declares a matching `static partial void Customize{MethodName}(TypeAdapterConfig config)`
+hook and calls it before returning. Implement it in your hand-written `Mapper` partial class to
+**add** custom mappings on top of the generated ones — compiler-checked, IntelliSense-assisted,
+and able to express null guards (which a projection through an optional navigation requires):
 
 ```csharp
-[ProjectToDTO(".Map(dest => dest.TransactionPrice, src => src.Transaction.Price)")]
-public class Achievement : BusinessObject<long>
+[SpiderlyDataMapper]
+public static partial class Mapper
 {
-    // ...
+    static partial void CustomizeOrderItemProjectToConfig(TypeAdapterConfig config)
+    {
+        // ProductVariant is an optional nav (nullable FK) — the guard is mandatory:
+        // an unguarded src.ProductVariant.ProductId LEFT JOINs to NULL and crashes the
+        // EF shaper with "Nullable object must have a value" at materialization.
+        config.ForType<OrderItem, OrderItemDTO>()
+            .Map(dest => dest.ProductId, src => src.ProductVariant != null ? (int?)src.ProductVariant.ProductId : null);
+    }
 }
 ```
 
-The string is appended directly to the generated `.NewConfig<Entity, EntityDTO>()` chain. Use this for simple field mappings that the generator doesn't produce automatically.
+Use `config.ForType<...>()` (get-or-extend), never `NewConfig` (replace) — the generated
+M2O/display-name mappings are already on the config when the hook runs. An unimplemented hook
+compiles away entirely; implementing a hook whose config method you also fully overrode (see below)
+is a compile error (`CS0759`), so a dead hook can't sit around silently.
 
-### `[ProjectToDTO]` only fills the value — the field must exist on the DTO
+**Precedence (verified against Mapster 7.4.0):** `.Map` is *first-registration-wins* — a hook
+`.Map` targeting a member the generator already mapped is a **silent no-op**, not an override.
+`.Ignore` *does* win over an earlier `.Map`. So from a hook you can **add** new member mappings and
+**suppress** generated ones, but you cannot **replace** a generated mapping's expression — that is
+exactly what the full-method override (below) remains for.
 
-`[ProjectToDTO]` adds a Mapster *mapping*; it does **not** create the property. If `dest.ProductId`
-is not a property on the DTO, the field **never appears in the generated Angular type**
-(`entities.generated.ts`) — `[ProjectToDTO]` fills a value that has nowhere to land. (A common
-false alarm: the value maps fine at runtime, so it looks like the frontend "didn't regenerate" —
-but a normal `dotnet build` *does* regenerate the Angular files; the property was just never on
-the DTO for the generator to emit.)
+### Convention flattening is OFF — unmapped extension props stay unmapped
 
-To add a computed/projected field end-to-end, declare the property on a `partial class {Entity}DTO`
-extension — it merges into the generated DTO automatically, no attribute needed — **then** map its value:
+Generated configs strip Mapster's flatten-by-name strategy (`NewStrictConfig()` in the generated
+mapper). Without this, a DTO extension prop named e.g. `ShippingTierIsBulky` would *silently*
+project through `src.ShippingTier.IsBulky` — and when that navigation is optional, the LEFT JOIN's
+NULL crashes the shaper on a non-nullable member. With flattening off, a prop you never mapped
+simply stays at its default; wire it deliberately via a `Customize*` hook.
+
+### The hook only fills the value — the field must exist on the DTO
+
+A mapping does **not** create the property. If `dest.ProductId` is not a property on the DTO, the
+field **never appears in the generated Angular type** (`entities.generated.ts`). Declare the
+property on a `partial class {Entity}DTO` extension — it merges into the generated DTO
+automatically, no attribute needed — **then** map its value in the hook:
 
 ```csharp
-// 1. The property — a partial extension of the generated OrderItemDTO. No [SpiderlyDTO]
-//    needed: a partial that extends a generated DTO is merged in by name.
+// The property — a partial extension of the generated OrderItemDTO. No [SpiderlyDTO]
+// needed: a partial that extends a generated DTO is merged in by name.
 public partial class OrderItemDTO
 {
     public int? ProductId { get; set; }
 }
-
-// 2. The value — [ProjectToDTO] on the entity fills it during projection.
-[ProjectToDTO(".Map(dest => dest.ProductId, src => src.ProductVariant.ProductId)")]
-public class OrderItem : BusinessObject<long> { /* ... */ }
 ```
 
 Then `dotnet build` the backend — the source generators run on build and the field appears
 in `entities.generated.ts`. There is no separate "regenerate" command; the build is it.
 
+> **Removed:** the string-based `[ProjectToDTO(".Map(...)")]` entity attribute. Its string DSL
+> could not express a null guard (the parser choked on anything beyond a bare dotted path), which
+> made unsafe projections through optional navs the *only* writable form. Move any existing usage
+> into the corresponding `Customize{Entity}ProjectToConfig` hook.
+
 ## Partial Method Override — Full Control
 
 For complex mapping logic, override the entire generated method. The generator **skips generation** for any method that already exists in the user's partial `Mapper` class (detected by method name match).
@@ -124,10 +147,9 @@ public static partial class Mapper
 
 | Scenario | Approach |
 |---|---|
-| Add a simple computed field to projection | `[ProjectToDTO(".Map(...)")]` on entity class |
-| Add multiple computed fields to projection | Stack multiple `[ProjectToDTO]` attributes |
-| Complex mapping with conditionals or method calls | Override the full method in `Mapper.cs` |
-| Change DTO → Entity mapping (e.g., ignore a field) | Override `{Entity}DTOToEntityConfig()` |
-| Change Excel export projection | Override `{Entity}ExcelProjectToConfig()` |
+| Add computed/custom fields to any config (projection, DTO, save, Excel) | Implement the matching `Customize{Entity}{Method}` partial hook |
+| Mapping through an optional navigation | `Customize*` hook with an explicit null guard |
+| Suppress a generated mapping | `Customize*` hook with `.Ignore(dest => dest.X)` |
+| Change or replace generated mappings | Override the full method in `Mapper.cs` |
 
 Most projects never need custom mappers — the generated mappings handle M2O, M2M display names, and standard field-to-field mapping automatically.

package/fesm2022/spiderly.mjs

@@ -3151,7 +3151,27 @@ class InitTopBarData extends BaseEntity {
     static { this.typeName = 'InitTopBarData'; }
 }
 
+/** Parses a JSON entry from web storage; missing or corrupted entries read as null. */
+function readStoredJson(storage, key) {
+    try {
+        return JSON.parse(storage.getItem(key) ?? 'null');
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes a value to web storage as JSON; the counterpart of readStoredJson. */
+function writeStoredJson(storage, key, value) {
+    storage.setItem(key, JSON.stringify(value));
+}
+
 class LayoutServiceBase {
+    /**
+     * Only the desktop collapse persists across reloads (a durable preference,
+     * like the data table's column layout); the rest of LayoutState is
+     * deliberately transient.
+     */
+    static { this.menuDesktopInactiveKey = 'spiderly-layout:menu-desktop-inactive'; }
     constructor(apiService, config, authService) {
         this.apiService = apiService;
         this.config = config;
@@ -3163,7 +3183,8 @@ class LayoutServiceBase {
             colorScheme: 'light',
         };
         this.state = {
-            staticMenuDesktopInactive: false,
+            staticMenuDesktopInactive: readStoredJson(localStorage, LayoutServiceBase.menuDesktopInactiveKey) ===
+                true,
             overlayMenuActive: false,
             profileSidebarVisible: false,
             profileDropdownSidebarVisible: false,
@@ -3200,6 +3221,7 @@ class LayoutServiceBase {
         if (this.isDesktop()) {
             this.state.staticMenuDesktopInactive =
                 !this.state.staticMenuDesktopInactive;
+            writeStoredJson(localStorage, LayoutServiceBase.menuDesktopInactiveKey, this.state.staticMenuDesktopInactive);
         }
         else {
             this.state.staticMenuMobileActive = !this.state.staticMenuMobileActive;
@@ -4179,23 +4201,14 @@ class SpiderlyDataTableComponent {
             localStorage.removeItem(this.columnsStateKey);
         }
         else {
-            localStorage.setItem(this.columnsStateKey, JSON.stringify(this.columnVisibilityOverrides));
+            writeStoredJson(localStorage, this.columnsStateKey, this.columnVisibilityOverrides);
         }
     }
     restoreColumnVisibility() {
         if (!this.columnsStateKey)
             return;
         this.columnVisibilityOverrides =
-            SpiderlyDataTableComponent.readStoredJson(localStorage, this.columnsStateKey) ?? {};
-    }
-    /** Parses a JSON entry from web storage; missing or corrupted entries read as null. */
-    static readStoredJson(storage, key) {
-        try {
-            return JSON.parse(storage.getItem(key) ?? 'null');
-        }
-        catch {
-            return null;
-        }
+            readStoredJson(localStorage, this.columnsStateKey) ?? {};
     }
     /**
      * PrimeNG's persisted table state (filters/sort/pagination), read directly from storage
@@ -4204,7 +4217,7 @@ class SpiderlyDataTableComponent {
     persistedTableState() {
         if (!this.resolvedStateKey)
             return null;
-        return SpiderlyDataTableComponent.readStoredJson(this.stateStorage === 'local' ? localStorage : sessionStorage, this.resolvedStateKey);
+        return readStoredJson(this.stateStorage === 'local' ? localStorage : sessionStorage, this.resolvedStateKey);
     }
     /**
      * Guards the "hidden contributes nothing" invariant against state this component didn't